Skip to content

Latest commit

 

History

History
181 lines (135 loc) · 5.25 KB

README_NIXOS.md

File metadata and controls

181 lines (135 loc) · 5.25 KB

maccel NixOS Flake

If you're on NixOS, maccel provides a declarative flake module to seamlessly integrate and configure the mouse acceleration driver through your system configuration.

Benefits of the NixOS module:

  • Declarative configuration: All parameters defined in your NixOS config
  • Direct kernel module parameters: More efficient than reset scripts approach
  • No manual setup: Kernel module, udev rules, and CLI tools installed automatically
  • Seamless updates: Update maccel alongside your system like any other flake
  • Parameter discovery: Optional CLI/TUI for real-time parameter tuning

Quick Start

Add to your flake.nix inputs:

maccel.url = "github:Gnarus-G/maccel";

Create your maccel.nix module:

{inputs, ...}: {
  imports = [
    inputs.maccel.nixosModules.default
  ];

  hardware.maccel = {
    enable = true;
    enableCli = true; # Optional

    parameters = {
      # Common (all modes)
      sensMultiplier = 1.0;
      yxRatio = 1.0;
      inputDpi = 1000.0;
      angleRotation = 0.0;
      mode = "synchronous";

      # Linear mode
      acceleration = 0.3;
      offset = 2.0;
      outputCap = 2.0;

      # Natural mode
      decayRate = 0.1;
      offset = 2.0;
      limit = 1.5;

      # Synchronous mode
      gamma = 1.0;
      smooth = 0.5;
      motivity = 2.5;
      syncSpeed = 10.0;
    };
  };

  # To use maccel CLI/TUI without sudo
  users.groups.maccel.members = ["your_username"];
}

How it Works

Parameter Management

  • NixOS config: Parameters are set directly as kernel module parameters at boot for maximum efficiency
  • CLI/TUI: When enableCli = true, you can use maccel tui or maccel set for real-time adjustments
  • Temporary changes: CLI/TUI modifications are session-only and revert after reboot

Recommended Workflow

  1. Enable CLI tools: Set enableCli = true for parameter discovery
  2. Find optimal values: Use maccel tui to experiment with parameters in real-time
  3. Apply permanently: Copy your optimal values to hardware.maccel.parameters in your NixOS config
  4. Rebuild system: Run sudo nixos-rebuild switch --flake . to make settings persistent

Maintaining the NixOS Module

When new acceleration modes or parameters are added to maccel, the NixOS module needs to be updated accordingly. This section provides a step-by-step guide for maintainers.

1. Adding New Modes

New modes are defined in driver/accel/mode.h. To add support:

In module.nix:

Step 1: Add to modeMap

# Update the modeMap with new modes
modeMap = {
  linear = 0;
  natural = 1;
  synchronous = 2;
  no_accel = 3;
  new_mode = 4;  # Add new mode here
};

Step 2: Add the mode option

# In options.hardware.maccel.parameters
mode = mkOption {
  type = types.nullOr (types.enum ["linear" "natural" "synchronous" "no_accel" "new_mode"]);
  default = null;
  description = "Acceleration mode.";
};

2. Adding New Parameters

New parameters are defined in driver/params.h. To add support:

In module.nix:

Step 1: Add to parameterMap

# In parameterMap
parameterMap = {
  # Existing parameters...
  NEW_PARAM = cfg.parameters.newParam;
};

Step 2: Add NixOS option

# In options.hardware.maccel.parameters
newParam = mkOption {
  type = types.nullOr types.float;  # or appropriate type
  default = null;
  description = "Description of the new parameter.";
};

Step 3: Add validation (if needed)

# For parameters with constraints
newParam = mkOption {
  type = types.nullOr (types.addCheck types.float (x: x > 0.0)
    // {description = "positive float";});
  default = null;
  description = "Description of the new parameter. Must be positive.";
};

3. Using LLMs

This NixOS module was developed with significant LLM assistance. Here's a comprehensive prompt for maintaining it:

I need to update the NixOS module for maccel. Please analyze the maccel codebase and help me maintain the NixOS module:

CONTEXT:
- maccel is a Linux mouse acceleration driver with kernel module and CLI tools
- The NixOS module is in module.nix and provides declarative configuration
- Parameters are defined in driver/params.h and modes in driver/accel/mode.h
- Read README_NIXOS.md section "Maintaining the NixOS Module" for detailed patterns and examples

TASKS:
1. **Discover changes**: Analyze driver/params.h and driver/accel/ for new parameters, modes, or modifications
2. **Compare with current**: Check what's missing from existing modeMap and parameterMap in module.nix
3. **Add new modes**: Update modeMap with correct enum values and add to mode option enum
4. **Add new parameters**: Add to parameterMap and create NixOS options with proper type validation, descriptions, and constraints
5. **Explain changes**: Summarize what was added and why

Follow the exact patterns shown in README_NIXOS.md and existing patterns in module.nix. Provide complete code snippets for module.nix.

4. Testing The Module

After modifying module.nix:

  1. Format nix code: alejandra .
  2. Check nix syntax: nix flake check
  3. Test parameter loading: Confirm parameters load correctly on boot when set via NixOS config