moonup

Manage multiple MoonBit installations

Getting Started

Install

Moonup is available for installation via different ways.

Conda (Cross-platform)

You can install moonup with conda/mamba/pixi from our conda-forge channel:

pixi global install moonup -c chawyehsu -c conda-forge

Cargo (Cross-platform, build from source)

If you have the Rust toolchain installed, you can install moonup easily with Cargo:

cargo install moonup

Homebrew (macOS)

If you are on macOS and you have Homebrew installed, you can install moonup from our Homebrew Tap:

brew install chawyehsu/brew/moonup

Scoop (Windows)

If you are on Windows and you have Scoop installed:

scoop bucket add dorado https://github.com/chawyehsu/dorado
scoop install moonup

GitHub Releases

Or you may download the latest release from GitHub releases, manually extract the archive and put the executables in a directory that is in your PATH.

Usage

After installation, run moonup help to see the available commands.

$ moonup help
Moonup is a tool to manage multiple MoonBit installations.

If you find any bugs or have a feature request, please open an issue on
GitHub: https://github.com/chawyehsu/moonup/issues

Usage: moonup [OPTIONS] <COMMAND>

Commands:
  completions  Generate shell completions
  default      Set the default toolchain
  install      Install or update a MoonBit toolchain [aliases: i]
  list         List installed and active toolchains [aliases: ls]
  pin          Pin the MoonBit toolchain to a specific version
  run          Run a command with a specific toolchain
  self-update  Update Moonup to the latest version
  uninstall    Uninstall a MoonBit toolchain
  update       Update MoonBit toolchains [aliases: u]
  which        Show the actual binary that will be run for a given command
  help         Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase logging verbosity
  -q, --quiet...    Decrease logging verbosity
  -h, --help        Print help
  -V, --version     Print version

Install a MoonBit Toolchain

# install the latest MoonBit toolchain
moonup install latest
# install the latest nightly MoonBit toolchain
moonup install nightly
# install a specific MoonBit toolchain (`v` prefix is not required)
moonup install 0.1.20241231+ba15a9a4e

Pin a MoonBit Toolchain

By pinning a MoonBit toolchain to a specific version in a project, the toolchain will be automatically switched to the pinned version when you're running MoonBit commands in the project directory. With this feature, you can ensure that the project is built and tested with the same MoonBit toolchain.

moonup pin 0.1.20241231+ba15a9a4e
# remove the `moonbit-version` file to unpin
rm moonbit-version

You're not required to install the pinned MoonBit toolchain in advance. Moonup will download and install the toolchain automatically when a command is run.

Set the Default Toolchain

The default toolchain is used when no toolchain is specified in a project. The latest toolchain is used by default.

# change the default toolchain to the latest nightly
moonup default nightly

Check Installed and Active Toolchains

moonup list

Run a Command with a Specific Toolchain

moonup run 0.1.20241231+ba15a9a4e moon version
# or pass the version to the command directly! (syntax: `+<spec>`)
moon +nightly version --all

Uninstall a MoonBit Toolchain

# relevant cached downloads will be removed as well
moonup uninstall 0.1.20241231+ba15a9a4e
# delete all cached downloads
moonup uninstall --clear

Use Moonup in GitHub Actions

With the setup-moonup action, It's super easy to use Moonup to set up a MoonBit environment in GitHub CI. Here is an example workflow:

- name: Setup MoonBit
  uses: chawyehsu/setup-moonup@v1
  run: moon version --all

Distribution Server

Moonup is backed by chawyehsu/moonbit-binaries, a service built with GitHub Actions to continuously archive MoonBit releases from the official website and provide a distribution server with a stable API.

The default dist server endpoint is https://moonup.csu.moe/v2 at the time of writing. Moonup supports overriding the distribution server with the MOONUP_DIST_SERVER environment variable.

# set the distribution server to a custom endpoint
export MOONUP_DIST_SERVER=https://moonup.corporate.internal/

With this feature, you can configure Moonup to fetch and install MoonBit toolchains from a custom distribution server. This is useful when the default distribution server is not accessible in your environment, or when you want to host your own distribution server for MoonBit toolchains.

You have to build up the distribution server yourself though.

How It Works

Moonup allows you to install multiple MoonBit toolchains and switch between them easily. All MoonBit toolchains (with the core standard library) are installed in Moonup's toolchains directory.

Moonup creates shim executables that replace the original MoonBit executables in the PATH. When you run a MoonBit command, the shim executable determines which MoonBit toolchain to use and proxies the command to the actual MoonBit executable in the desired toolchain.

With this approach, you can switch between MoonBit toolchains across projects easily without needing to change the PATH.

Known Limitations

• Isolation of MoonBit core standard library is problematic, see #7.

Development

Prerequisites: Git, pixi

# clone the repo
git clone https://github.com/chawyehsu/moonup
cd moonup
# install dependencies
pixi install
# install git prek(pre-commit) hooks
pixi run prek install
# dev build and run
pixi run cargo run moonup -- help
# run tests
pixi run test
# enter dev environment shell
pixi shell
# dev tools available in the shell

0.1.0 Roadmap

• An install command to install multiple MoonBit toolchains
• A pin command to pin toolchain to a specific version in a project
• Create shim executables to switch between toolchains automatically
• A default command to set the default toolchain
• A show command to show installed and currently active toolchains
• A which command to show the actual binary that will be run for a given command
• A run command to run a command with a specific toolchain
• A update command to self-update and update the toolchain
• A completions command to generate shell completions

License

moonup © Chawye Hsu. Released under the Apache-2.0 license.

Blog · GitHub @chawyehsu · Twitter @chawyehsu