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 foremanTo 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
reposcope - Once created, you may need to click the
Configure SSObutton 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
foremanper the instructions above. - Delete the
~/.foreman/tool-cache.jsonfile and the~/.foreman/tools/folder (and its contents), as well as the~/.foreman/binfolder (as described in the Upgrading section above). This should remove any invalid binaries that foreman has cached. - Run
foreman installto 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.
