🚀 cargo.nvim

---

📦 A Neovim plugin that provides seamless integration with Rust's Cargo commands. Execute Cargo commands directly from Neovim with a floating window interface.

✨ Features

• 🔧 Execute Cargo commands directly from Neovim
• 🪟 Real-time output in floating windows
• 🎨 Syntax highlighting for Cargo output
• ⚡ Asynchronous command execution
• 🔄 Auto-closing windows on command completion
• ⌨️ Easy keyboard shortcuts for window management
• 📟 Terminal mode for interactive applications

📑 Table of Contents

• 🚀 cargo.nvim
  • ✨ Features
  • 📑 Table of Contents
  • 📥 Installation
    • Using lazy.nvim
    • Using packer.nvim
  • 📋 Requirements
  • 🛠️ Available Commands
  • ⚙️ Configuration
  • ⌨️ Key Mappings
  • 🔄 Interactive Mode
  • 📟 Terminal Mode
  • 👥 Contributing
  • 📜 License
  • 💝 Acknowledgements
  • 🎉 Related Projects

📥 Installation

Using lazy.nvim

{
  "nwiizo/cargo.nvim",
  build = "cargo build --release",
  config = function()
    require("cargo").setup({
      float_window = true,
      window_width = 0.8,
      window_height = 0.8,
      border = "rounded",
      auto_close = true,
      close_timeout = 5000,
    })
  end,
  ft = { "rust" },
  cmd = {
    "CargoBench",
    "CargoBuild", 
    "CargoClean",
    "CargoDoc",
    "CargoNew",
    "CargoRun",
    "CargoRunTerm",
    "CargoTest",
    "CargoUpdate",
    "CargoCheck",
    "CargoClippy",
    "CargoAdd",
    "CargoRemove",
    "CargoFmt",
    "CargoFix"
  }
}

Using packer.nvim

use {
  "nwiizo/cargo.nvim",
  run = "cargo build --release",
  config = function()
    require("cargo").setup({
      float_window = true,
      window_width = 0.8,
      window_height = 0.8,
      border = "rounded",
      auto_close = true,
      close_timeout = 5000,
    })
  end,
}

📋 Requirements

• 💻 Neovim >= 0.9.0
• 🦀 Rust and Cargo installed on your system
• 📚 Additional dependencies:
  • Ubuntu/Debian: libluajit-5.1-dev (Install with sudo apt install libluajit-5.1-dev)
  • macOS: luajit (Install with brew install luajit)
  • For other Linux distributions, you may need to install an equivalent LuaJIT development package

If you encounter build errors mentioning lluajit-5.1 during installation, you likely need to install the LuaJIT development package for your system.

🛠️ Available Commands

Core Commands

• 📊 :CargoBench - Run benchmarks
• 🏗️ :CargoBuild - Build the project
• 🧹 :CargoClean - Remove generated artifacts
• 📚 :CargoDoc - Generate project documentation
• ✨ :CargoNew - Create a new Cargo project
• ▶️ :CargoRun - Run the project in a floating window
• 📟 :CargoRunTerm - Run the project in terminal mode (better for interactive applications)
• 🧪 :CargoTest - Run tests
• 🔄 :CargoUpdate - Update dependencies

Additional Commands

• 🔍 :CargoCheck - Check the project for errors
• 📋 :CargoClippy - Run the Clippy linter
• ➕ :CargoAdd - Add dependency
• ➖ :CargoRemove - Remove dependency
• 🎨 :CargoFmt - Format code with rustfmt
• 🔧 :CargoFix - Auto-fix warnings
• 📦 :CargoPublish - Publish package
• 📥 :CargoInstall - Install binary
• 📤 :CargoUninstall - Uninstall binary
• 🔎 :CargoSearch - Search packages
• 🌲 :CargoTree - Show dependency tree
• 📦 :CargoVendor - Vendor dependencies
• 🛡️ :CargoAudit - Audit dependencies
• 📊 :CargoOutdated - Check outdated dependencies
• 🤖 :CargoAutodd - Automatically manage dependencies

⚙️ Configuration

You can customize cargo.nvim by passing options to the setup function:

require("cargo").setup({
  -- Window settings
  float_window = true,          -- Use floating window
  window_width = 0.8,           -- Window width (80% of editor width)
  window_height = 0.8,          -- Window height (80% of editor height)
  border = "rounded",           -- Border style ("none", "single", "double", "rounded")
  wrap_output = true,           -- Enable text wrapping in output window
  show_line_numbers = true,     -- Show line numbers in output window
  show_cursor_line = true,      -- Highlight current line in output window
  
  -- Auto-close settings
  auto_close = true,            -- Auto close window on success
  close_timeout = 5000,         -- Close window after 5000ms
  
  -- Timeout settings
  run_timeout = 300,            -- Timeout for cargo run in seconds
  interactive_timeout = 30,     -- Inactivity timeout for interactive mode
  
  -- Advanced behavior options
  force_interactive_run = true, -- Always treat cargo run as interactive mode
  max_inactivity_warnings = 3,  -- Maximum number of inactivity warnings before termination
  detect_proconio = true,       -- Enable detection of proconio usage
  force_smart_detection = true, -- Always use smart detection for interactive programs
  
  -- Key mappings (customizable)
  keymaps = {
    close = "q",
    scroll_up = "<C-u>",
    scroll_down = "<C-d>",
    scroll_top = "gg",
    scroll_bottom = "G",
    interrupt = "<C-c>",
    toggle_wrap = "w",
    copy_output = "y",
    clear_output = "c",
  },
})

⌨️ Key Mappings

In the floating window:

• q or <Esc> - Close the window
• <C-c> - Cancel the running command
• <C-u> - Scroll up
• <C-d> - Scroll down
• gg - Scroll to top
• G - Scroll to bottom
• w - Toggle text wrapping
• y - Copy all output to clipboard
• c - Clear output

🔄 Interactive Mode

For interactive programs that require user input:

• An input field appears at the bottom of the window when needed
• Enter your input and press Enter to send it to the program
• The plugin automatically detects when a program is waiting for input
• The window automatically closes after a period of inactivity (configurable)
• Interactive mode timeout prevents hanging processes and memory leaks

📟 Terminal Mode

For highly interactive applications (e.g., using proconio or TUI applications):

• Use :CargoRunTerm to run your application in a terminal emulator inside a floating window
• Supports full terminal capabilities for interactive Rust applications
• Useful for:
  • Competitive programming with libraries like proconio
  • Text-based UI applications
  • Programs requiring advanced terminal input/output
• Provides a better experience than the standard :CargoRun for interactive applications

Terminal Mode Key Mappings

• q or <Esc> - Close the window (after program completion)
• <C-\><C-n> - Switch to normal mode (while running)
• <C-c> - Send interrupt signal
• <C-d> - Send EOF signal

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. ✍️ Commit your changes
4. 🚀 Push to the branch
5. 📫 Open a Pull Request

📜 License

MIT License - see the LICENSE file for details.

💝 Acknowledgements

This plugin is inspired by various Neovim plugins and the Rust community.

🎉 Related Projects

• cargo-autodd - A tool for automatic dependency management