Add NixOS support ❄️

[avisek]

❄️ Add NixOS Support

Summary

This PR adds comprehensive NixOS support to maccel through a flake module, enabling NixOS users to declaratively configure mouse acceleration parameters directly in their system configuration with all parameters support.

Motivation

NixOS users have been unable to easily use maccel due to the imperative installation process and lack of declarative configuration options. This addition brings maccel to the NixOS ecosystem with first-class support, making it accessible to thousands of NixOS users who prefer declarative system management.

Features

🎯 Declarative Configuration

• All acceleration parameters configurable through hardware.maccel.parameters
• Parameters applied directly as kernel module parameters for maximum efficiency
• Type-safe configuration with proper validation
• No manual kernel module or udev rule installation required

🔧 Optional CLI/TUI Integration

• enableCli option to install CLI tools for parameter discovery
• Real-time parameter tuning with maccel tui
• Session-only changes that don't interfere with NixOS config
• Seamless workflow: experiment with CLI → apply permanently via config

📦 Complete Integration

• Automatic kernel module building and loading
• Proper udev rules and permissions setup
• User group management (maccel group)
• Debug build support via debug option
• Optional CLI/TUI for parameter discovery

⚡ Enhanced Efficiency

• Direct kernel module parameter approach (vs reset scripts used in standard installation)
• Parameters revert to declared values after reboot

Implementation

Files Added

• flake.nix - Simple flake exporting the NixOS module
• module.nix - Full NixOS module with all possible configuration support
• README_NIXOS.md - Detailed NixOS-specific documentation

Key Components

• Kernel Module Build: Integrates with NixOS kernel package system
• Fixed-Point Conversion: Automatic conversion of float parameters to kernel-compatible fixed-point integers
• Parameter Mapping: Complete mapping of all driver parameters to NixOS options
• CLI Integration: Optional Rust package building for CLI tools

Usage Example

# flake.nix
{
  inputs.maccel.url = "github:Gnarus-G/maccel";
}

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

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

    parameters = {
      mode = "linear";
      sensMultiplier = 1.0;
      acceleration = 0.3;
      offset = 2.0;
      outputCap = 2.0;
    };
  };

  users.groups.maccel.members = ["username"];  # For CLI access without sudo
}

Workflow Benefits

1. Discovery: Use maccel tui to find optimal parameters in real-time
2. Configuration: Apply discovered values permanently in NixOS config
3. Persistence: Parameters automatically load on every boot via kernel module parameters
4. Reproducibility: Identical configuration across multiple machines

Documentation Updates

• README.md: Added NixOS installation section with concise example
• README_NIXOS.md: Comprehensive NixOS-specific guide with:
  • Quick start instructions
  • Parameter management explanation
  • Recommended workflow
  • All available options

Testing Considerations

The module has been tested with:

• ✅ Kernel module compilation and loading
• ✅ Parameter application and persistence
• ✅ CLI tool functionality when enabled
• ✅ Proper permissions and group setup
• ✅ All acceleration modes (linear, natural, synchronous, no_accel)

Impact

This addition makes maccel accessible to the growing NixOS community while maintaining the same powerful functionality users expect. The declarative approach aligns perfectly with NixOS philosophy and provides a superior user experience compared to imperative installation methods.

Related

• Closes potential NixOS user requests
• Enables inclusion in NixOS package collections
• Positions maccel as the most complete mouse acceleration solution for Linux

---

Ready for the NixOS community! 🚀

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
maccel	Error			Sep 6, 2025 5:05pm

[avisek]

Hey @Gnarus-G! Just wanted to follow up on this NixOS support PR.

This adds first-class NixOS integration with zero maintenance overhead for you - it's completely self-contained in the flake module. The implementation follows NixOS best practices and handles all the kernel module building, parameter management, and permissions automatically.

Given NixOS's growing popularity in the Linux enthusiast community (especially among users who care about precise system control like mouse acceleration), this could bring maccel to a significant new user base who currently can't easily use it.

The code is fully tested and ready to go - would love to get this merged so NixOS users can start benefiting from maccel's excellent acceleration algorithms! 🚀

Let me know if you have any questions or need any changes.

[Gnarus-G]

@avisek Thank you for PR.

I don't use nix and I don't have the time/interest to understand this PR deeply.
I'll merge it if you:

• think there's a high likelihood that you'd make offer more PR's if there are issues related to it.
• document how to update the config to support any new modes/parameters we might implement.

P.S Which LLM model did you use when developing this PR? Seems thorough.

[avisek]

@avisek Thank you for PR.

I don't use nix and I don't have the time/interest to understand this PR deeply. I'll merge it if you:

• think there's a high likelihood that you'd make offer more PR's if there are issues related to it.
• document how to update the config to support any new modes/parameters we might implement.

P.S Which LLM model did you use when developing this PR? Seems thorough.

@Gnarus-G Thanks for the response!

First off, apologies for the late response - I was traveling.

Maintenance Commitment: Absolutely! I've been using NixOS as my daily driver for quite some time now, moving from Arch, and I'm committed to it long-term. As long as maccel remains the best mouse acceleration driver on Linux, I'll ensure it works seamlessly on NixOS. The beauty of this implementation is that it's completely self-contained with very minimal maintenance overhead.

Documentation: I've added comprehensive maintenance documentation directly to README_NIXOS.md that explains exactly how to update the NixOS module for any new modes/parameters. It includes:

• Step-by-step workflow for adding new parameters/modes
• Parameter discovery process and source file mapping
• Code examples, validation patterns, and testing procedures
• Complete LLM prompt template for automated updates

LLM Used: I used claude-4-sonnet-thinking on Cursor. I believe it's all a matter of giving the right context and prompt.

P.S. If you're ever curious about NixOS, I'd highly encourage checking it out! The declarative approach and reproducibility make it incredibly developer-friendly. Many consider it the "endgame" of Linux distributions - once you experience the simplicity of declarative system management, it's hard to go back. 🚀

Ready to get this merged and bring maccel to the NixOS community!