DOCSEARCHbyAlgolia
Submit Docs

rokit

repository·main·Indexed 19 days ago

https://github.com/rojo-rbx/rokit

A next-generation toolchain manager for Roblox projects designed for speed and community-first development. Rokit provides drop-in compatibility with Foreman and Aftman, offering faster installation and improved cross-platform consistency. It includes a CLI for managing tools via a rokit.toml manifest, supporting commands such as init, add, list, install, and update.

Tokens
7.2K
Snippets
32
Records
37
Agent score
62%

What's inside rokit

  1. Install Rokit on Windows

    main

    There are two primary ways to install Rokit on Windows:

    Option 1: PowerShell Script

    Run the automated installer script in PowerShell:

    Invoke-RestMethod https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.ps1 | Invoke-Expression

    Option 2: Manual Executable

    1. Download rokit.exe from the latest release page.
    2. Double-click the file in File Explorer to trigger the automatic installation.
    3. If you prefer to install via a terminal (PowerShell/CMD), run: rokit.exe self-install

  2. Install Rokit from source

    main

    If you are on a compatible system, you can compile and install Rokit using cargo:

    1. Install the binary: cargo install rokit --locked
    2. Initialize directories and data files: rokit self-install
    cargo install rokit --locked
rokit self-install

  3. Install Rokit on macOS & Linux

    main

    To install Rokit on macOS or Linux, run the automated installer script via curl in your terminal.

    curl -sSf https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.sh | bash

  4. How Rokit's dual modes of operation work

    main

    Rokit operates in one of two modes depending on whether it is currently wrapping a tool executable:

    1. Wrapper Mode: If Rokit is wrapping a tool executable, it runs that executable and pipes its output back to the user. In this mode, it acts as a transparent proxy for the tool.
    2. CLI Mode: If Rokit is not wrapping a tool, it runs its own CLI interface used for managing and installing tools.

    This allows Rokit to serve both as a package manager and as a runtime execution layer for the tools it manages.

  5. Use the Descriptor struct to represent system environments

    main

    The Descriptor struct represents a system's environment, including its operating system (OS), architecture (Arch), and preferred toolchain (Toolchain). It is used to define target environments and check for compatibility between different systems (e.g., checking if a tool built for one architecture can run on another).

    Key capabilities:

    • Detecting the current system: Retrieve the host's OS, architecture, and toolchain.
    • Parsing from strings: Convert platform strings (like windows-x64-msvc) into a Descriptor.
    • Compatibility checking: Determine if a tool described by one Descriptor is compatible with another, accounting for emulation (e.g., macOS Apple Silicon running x64).
    • Binary detection: Extract system information directly from the bytes of an executable file.
    use rokit::descriptor::{Descriptor, OS, Arch, Toolchain};

// Get the current host system
let current = Descriptor::current_system();

// Parse a specific platform string
let target = "windows-x64-msvc".parse::<Descriptor>().unwrap();

// Check if the target is compatible with the current system
if current.is_compatible_with(&target) {
    println!("Target is compatible");
}

  6. The `rokit.toml` manifest file format

    main

    Rokit uses a rokit.toml file to manage and list the tools used in a project. The manifest contains a [tools] table where each entry consists of a tool alias (the key) and a tool specification (the value, stored as a string).

    # This file lists tools managed by Rokit, a toolchain manager for Roblox projects.
# For more information, see <|REPOSITORY_URL|>

# New tools can be added by running `rokit add <tool>` in a terminal.

[tools]
# Example entry: alias = "tool_spec_string"

  7. Configure authentication tokens in auth.toml

    main

    Rokit manages authentication tokens for various artifact providers using a file named auth.toml. This file stores tokens as key-value pairs where the key is the name of the ArtifactProvider and the value is the authentication token string.

    Example auth.toml structure:

    # This file lists authentication tokens managed by Rokit, a toolchain manager for Roblox projects.
# For more information, see <|REPOSITORY_URL|>

github = "ghp_tokenabcdef1234567890"
    # This file lists authentication tokens managed by Rokit, a toolchain manager for Roblox projects.
# For more information, see <|REPOSITORY_URL|>

# github = "ghp_tokenabcdef1234567890"

  8. Rokit CLI command reference

    main

    Use rokit --help for a full overview of all commands, or rokit <command-name> --help for specific details on a single command.

    Available Commands

    CommandDescription
    initInitializes a new project in the current directory.
    addAdds and installs a tool.
    listLists all currently installed tools.
    installInstalls all project-specific tools.
    updateUpdates a specific tool, or all project-specific tools, to the latest version.
    authenticateAuthenticates with GitHub or other artifact providers.
    self-updateUpdates Rokit itself to the latest version.
    self-installInstalls Rokit itself and updates tool executable links.

  9. Retrieve tool specifications from a `RokitManifest`

    main

    To inspect the tools currently managed by a manifest, use the following methods:

    • has_tool(&alias): Returns true if the manifest contains a tool with the specified ToolAlias.
    • get_tool(&alias): Returns Some(ToolSpec) if the tool exists, or None otherwise.
    • tool_specs(): Returns a Vec<(ToolAlias, ToolSpec)> containing all valid tool definitions found in the [tools] table. Invalid specifications are ignored.
    // Check for a specific tool
if manifest.has_tool(&alias) {
    let spec = manifest.get_tool(&alias).unwrap();
}

// Iterate over all valid tools
for (alias, spec) in manifest.tool_specs() {
    println!("Found tool: {:?} with spec: {:?}", alias, spec);
}

  10. Create a tool source client with `create_client`

    main

    Use create_client to instantiate a ClientWithMiddleware configured for interacting with tool sources. The client is pre-configured with the following behaviors:

    • Security: HTTPS only.
    • Timeouts: 15-second connection timeout and a 60-second total request timeout.
    • Compression: Supports gzip, brotli, and deflate.
    • User Agent: Automatically sets a User Agent header in the format <crate_name>/<crate_version> (<repository_url>).
    • Resiliency: Includes middleware for retrying failed requests using an exponential backoff policy (up to 3 retries).
    • Observability: Includes tracing middleware for HTTP requests.

    To use this function, provide a reqwest::header::HeaderMap containing any additional default headers you require.

    use reqwest::header::HeaderMap;
// Assuming the crate is imported as `rokit`
let mut headers = HeaderMap::new();
let client = rokit::create_client(headers).expect("Failed to create client");

  11. Add or update tools in a `RokitManifest`

    main

    Use add_tool and update_tool to modify the toolset in a manifest instance. These methods return a boolean indicating whether the operation was successful.

    • add_tool(&alias, &spec): Adds a tool if the alias does not already exist. Returns false if the tool is already present.
    • update_tool(&alias, &spec): Updates an existing tool's specification. Returns false if the tool does not exist.
    // Returns true if the tool was added
if manifest.add_tool(&alias, &spec) {
    println!("Tool added!");
}

// Returns true if the tool was updated
if manifest.update_tool(&alias, &spec) {
    println!("Tool updated!");
}

  12. Check compatibility between Descriptors

    main

    The is_compatible_with method determines if one Descriptor can run on the system described by another. Compatibility requires the operating systems to match exactly. Architectures are compatible if they match exactly, or in these specific emulation cases:

    • Windows/Linux: 64-bit (X64) can run 32-bit (X86) executables.
    • macOS Apple Silicon: Arm64 can run X64 (Intel) executables.

    Note: macOS universal binaries are treated as X64 for compatibility purposes.

    let host = Descriptor::current_system();
let tool = "macos-x64".parse::<Descriptor>().unwrap();

if host.is_compatible_with(&tool) {
    // This will be true on an Apple Silicon Mac
}