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!
You can download pre-built Foreman releases for Windows, macOS, and Linux from the Releases page.
You can use the official setup-foreman action to install Foreman as part of your GitHub Actions workflow.
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).
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.
Most users will want to do a bit of additional setup to begin using tools via foreman.
On first run (try foreman list
), Foreman will create a .foreman
directory in your user folder (usually $HOME/.foreman
on Unix systems, %USERPROFILE%/.foreman
on Windows).
It's recommended that you add $HOME/.foreman/bin
to your PATH
to make the tools that Foreman installs for you accessible on your system. If you have tools installed via other mechanisms (for example, you may have previously installed rojo
directly via cargo
), ensure that $HOME/.foreman/bin
is on your PATH before any other installation directories like .cargo/bin
in order to make sure it takes precedence.
If you're using bash or zsh, you can add this line to your ~/.bash_profile
or your ~/.zprofile
file (respectively):
export PATH=$HOME/.foreman/bin:$PATH
To install tools from a private GitHub repository, Foreman supports authenticating with a Personal Access Token. When creating the token in GitHub:
- Make sure to configure the token to have access to the
repo
scope - Once created, you may need to click the
Configure SSO
button next to the token to authorize it for SSO usage. Whether or not you need to do this will depend on the GitHub org that you need to access.
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
.
Foreman downloads tools from GitHub or GitLab and references them by their user/repo
name, like Roblox/foreman
.
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.
foreman supports Github and Gitlab as hosts by default, but you can define your own custom hosts as well using a single hosts
entry and an enumeration of the hosts you want to download tools from, which looks like this.
[hosts]
# default hosts
# source = {source = "https://github.com", protocol = "github"}
# github = {source = "https://github.com", protocol = "github"}
# gitlab = {source = "https://gitlab.com", protocol = "gitlab"}
artifactory = {source = "https://artifactory.com", protocol = "artifactory"}
[tools]
tool = {artifactory = "tools/tool", version = "1.1.0"}
foreman currently only supports github, gitlab, and artifactory as protocols.
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!
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.
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.
If you're using foreman version 1.0.4 or older on a non-M1 Mac, you may have encounter an error that looks like this:
an error happened trying to run `github.com/some-org/some-tool@^1.2.3` at `/Users/some-user/.foreman/tools/some-org__some-tool-1.2.3` (this is an error in Foreman): Bad CPU type in executable (os error 86)
In this case, your foreman installation has mistakenly downloaded an incompatible version of the tool binary due to an error in the binary file selection logic.
If you're using foreman version 1.1.0 or older, you may encounter an error that reads like this when an existing project adds a Windows binary for the aarch64
platform (eg Windows Holographic OS for HoloLens)
In this case, your foreman installation has mistakenly downloaded an incompatible version of the tool binary due to yet another error in the binary file selection logic.
To fix both of these error types, take the following steps:
- Upgrade your version of
foreman
per the instructions above. - Delete the
~/.foreman/tool-cache.json
file and the~/.foreman/tools/
folder (and its contents), as well as the~/.foreman/bin
folder (as described in the Upgrading section above). This should remove any invalid binaries that foreman has cached. - Run
foreman install
to re-download all relevant tools.
Your downloaded tools should now work correctly.
Foreman is available under the MIT license. See LICENSE.txt or https://opensource.org/licenses/MIT for details.