cargo-nvim 0.1.5

A Neovim plugin for Rust Cargo commands
Documentation

🚀 cargo.nvim

Rust CI Lua CI

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

cargo.nvim demo

✨ 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

📥 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