Kissb Alternatives Module Documentation

---

The Kissb Alternatives Module allows you to manage multiple versions of tools (e.g., SDKs, compilers, or runtime environments) in your environment. It works similarly to tools like SDKMan, nvm, or pyenv, enabling you to switch between versions seamlessl using a simple call in terminal:

kissb -q .alternatives.use <tool> <version>?

The following tools are currently supported by KISSB core packages:

Tool	Description	Global Version variable
jvm	JDK - Provided by the Scala Coursier tool	jvm.default.version
coursier	Scala Coursier	none, coursier is always installed as latest
maven	Maven Build System (mvn)	maven.version
maven daemon	Maven Daemon (mvnd)	maven.daemon.version
gradle	Gradle Build System	gradle.version
quarkus	Quarkus CLI tool	quarkus.version

• Ensure Kissb is installed and configured in your environment.
• The module requires a Bash-compatible terminal for environment setup.
• You can use the global tool version variable to configure a tool version once in a config file

Setup Instructions

2. Load the Environment

To load the configured environment variables and tool paths into your terminal, run:

eval "$(kissb --nobuild -q .alternatives.bashEnv)"

- This command updates your PATH and sets environment variables for the selected tool version. - You can add this command to your .bashrc after kissb is loaded

1. Install a Tool Version

To install a specific version of a tool (e.g., jvm, gradle, or python), use the following command:

kissb -q .alternatives.use <group> <version>

- Replace <group> with the tool group (e.g., jvm, gradle). - Replace <version> with the desired version. If omitted, the default version will be installed.

Example:

kissb -q --nobuild .alternatives.use jvm 17

3. Verify the Setup

To check the current configuration, use:

kissb -q .alternatives.display

- This displays the active tool versions and their configurations.

Troubleshooting

• If a tool version is not found, ensure the corresponding package is installed.
• If environment variables are not applied, verify that the eval command was executed correctly.

---

Provide a tool via the Alternatives Module

Developers and package maintainers can use the Alternatives Module to provide users with the ability to install and switch between tool versions. This section explains how to integrate the module into your package.

**1. alternatives.setup command **

Registers a tool version and its configuration in the alternatives system.

Parameters: - group: The tool group (e.g., jvm, gradle). - version: The version of the tool. - specs: A dictionary containing: - bin: Maps binary names to their target paths. - links: Maps directory link names to their target paths. - env: Defines environment variables to set (e.g., JAVA_HOME). - info: Additional information for the user.

Example from the JVM package:

alternatives.setup jvm 17 {
    bin {
        java /path/to/java
        javac /path/to/javac
    }
    env {
        JAVA_HOME { value /path/to/jdk merge 0 }
    }
} {}

2. Alternative provider handler

When the user calls the alternatives.use

---

Integration Steps

1. Define a Configuration Method In your package, define a method named <group>.alternatives.provide to handle version-specific configurations.

Example:

proc ::jvm.alternatives.provide {args} {
    # Parse arguments (e.g., --version)
    set version [dict get $args --version]

    # Call alternatives.setup with the appropriate specs
    ::kissb::alternatives::setup jvm $version {
        bin {
            java /path/to/java
            javac /path/to/javac
        }
        env {
            JAVA_HOME { value /path/to/jdk merge 0 }
        }
    } "OpenJDK $version"
}

1. Register the Package Ensure your package is loaded by Kissb and provides the <group>.alternatives.provide method.

---

Best Practices

• Error Handling: Ensure your package handles errors gracefully (e.g., missing versions or invalid paths).
• User Feedback: Provide clear feedback when a tool version is configured or changed.
• Documentation: Document the available tool groups and versions for users.

---