Foreman

Foreman is a toolchain manager to help Roblox developers manage their installations of tools like Rojo, Remodel, Tarmac, DarkLua, StyLua, and Selene.

Foreman is inspired by rustup and asdf.

It's used in production across hundreds of engineers, but more feedback is welcome!

Installation

GitHub Releases

You can download pre-built Foreman releases for Windows, macOS, and Linux from the Releases page.

GitHub Actions

You can use the official setup-foreman action to install Foreman as part of your GitHub Actions workflow.

Upgrading

First, replace your current version of Foreman with the newest one from the GitHub releases. If you don't remember where you have put the executable, running where foreman on Windows or which foreman on macOS and Linux should help you find it.

The other step is to locate the bin directory created by foreman and delete the files there. It is as simple as opening .foreman/bin, which is located under the user directory (%homepath% on Windows or $HOME on macOS and Linux).

From Source

If you have Rust 1.53.0 or newer installed, you can also compile Foreman by installing it from crates.io:

cargo install foreman

To upgrade, re-run cargo install foreman and clean up the bin directory as described in the section just above.

Usage

Foreman downloads tools from GitHub or GitLab and references them by their user/repo name, like Roblox/foreman.

On first run (try foreman list), Foreman will create a .foreman directory in your user folder (usually ~/.foreman on Unix systems, %USERPROFILE%/.foreman on Windows).

It's recommended that you add ~/.foreman/bin to your PATH to make the tools that Foreman installs for you accessible on your system.

Configuration File

Foreman uses TOML for its configuration file. It simply takes a single tools entry and an enumeration of the tools you need, which looks like this:

[tools]
rojo = { github = "rojo-rbx/rojo", version = "7.0.0" }
darklua = { gitlab = "seaofvoices/darklua", version = "0.7.0" }

As you may already have noticed, the tool name is located at the left side of = and the right side contains the information necessary to download it. For GitHub tools, use github = "user/repo-name" and for GitLab, use gitlab = "user/repo-name".

Previously, foreman was only able to download tools from GitHub and the format used to be source = "rojo-rbx/rojo". For backward compatibility, foreman still supports this format.

System Tools

To start using Foreman to manage your system's default tools, create the file ~/.foreman/foreman.toml.

A Foreman config that lists Rojo could look like:

[tools]
rojo = { github = "rojo-rbx/rojo", version = "7.0.0" }

Run foreman install from any directory to have Foreman pick up and install the tools listed in your system's Foreman config.

Now, if you run rojo inside of a directory that doesn't specify its own version of Rojo, Foreman will run the most recent 0.5.x release for you!

Project Tools

Managing a project's tools with Foreman is similar to managing system tools. Just create a foreman.toml file in the root of your project.

A Foreman config that lists Remodel might look like this:

[tools]
remodel = { github = "rojo-rbx/remodel", version = "0.9.1" }

Run foreman install to tell Foreman to install any new binaries from this config file.

When inside this directory, the remodel command will run the latest 0.6.x release of Remodel installed on your system.

Authentication

To install tools from a private GitHub repository, Foreman supports authenticating with a Personal Access Token.

Use foreman github-auth to pass an authentication token to Foreman, or open ~/.foreman/auth.toml and follow the contained instructions.

Similarly, for projects hosted on a GitLab repository, use foreman gitlab-auth to pass an authentication token to Foreman, or open ~/.foreman/auth.toml.

Troubleshooting

Foreman is a work in progress tool and has some known issues. Check out the issue tracker for known bugs.

If you have issues with configuration, you can delete ~/.foreman to delete all cached data and start from scratch. This directory contains all of Foreman's installed tools and configuration.

License

Foreman is available under the MIT license. See LICENSE.txt or https://opensource.org/licenses/MIT for details.

Anaminus / foreman