emacs-r-devkit

Professional Emacs environment for R package development on macOS

---

✨ Features

A complete, integrated development environment for R package development within Emacs:

• 🔍 ESS Integration - Full Emacs Speaks Statistics support with R console and code evaluation
• ✅ Flycheck + Linters - Real-time syntax checking with lintr and custom styler integration
• 🚀 LSP Mode - Language Server Protocol for intelligent code navigation and refactoring
• 💡 Smart Completion - Company mode with context-aware autocompletion
• 📝 Roxygen2 Automation - Automatic documentation skeleton generation with parameter detection
• 🎨 Auto-Formatting - Styler integration for automatic code formatting on save
• 🔷 S7 Support - Built-in snippets and helpers for R's new S7 OOP system
• 📦 Usethis Integration - Quick commands for creating R files, tests, and documentation
• 🔗 Git Integration - Magit for visual Git operations
• 📚 Quarto/LaTeX - Full support for Quarto documents and LaTeX writing

🚀 Quick Start

Prerequisites

• macOS 12.0+ (tested on macOS 12+)
• Emacs 27.1+ (emacs-plus recommended)
• R 4.0+
• Homebrew (recommended)

Installation

# Clone the repository
git clone https://github.com/Data-Wise/emacs-r-devkit.git
cd emacs-r-devkit

# Run installer
./install-init.sh

# Install required R packages
Rscript -e 'install.packages(c("devtools", "usethis", "roxygen2", "testthat", "lintr", "styler", "languageserver"))'

# Verify installation
./check-dependencies.sh

First Launch

# Start Emacs (first launch takes 10-15 minutes for package installation)
emacs

# Or use GUI
open -a Emacs

Note: The first launch downloads and compiles packages from MELPA. Subsequent launches are fast (<5 seconds).

📚 Documentation

Comprehensive documentation is available at data-wise.github.io/emacs-r-devkit

• Getting Started - Installation and setup guide
• Features - Detailed feature documentation
• Keybindings - Complete keybinding reference for macOS
• Configuration - Customization options
• Troubleshooting - Common issues and solutions
• Testing - Verification guide

🎯 Key Keybindings

Key	Action	Description
⌃ g	Cancel	Escape/cancel (use when stuck!)
⌃ x ⌃ f	Find file	Open file
⌃ x ⌃ s	Save	Save file
⌥ x	Execute	Run command
⌃ c r	R prefix	emacs-r-devkit commands
⌃ c r r	Roxygen	Insert documentation
⌃ ⏎	Send to R	Execute line/region
⌥ .	Go to def	Jump to definition
⌃ c ! l	List errors	Show Flycheck errors

Note: ⌥ = Option key (Meta), ⌃ = Control, ⇧ = Shift, ⌘ = Command

See the complete keybinding reference for more.

🔧 What's Included

Emacs Configuration (init.el)

• Package Management - Automatic package installation via MELPA
• ESS (R Mode) - Full R integration with console and evaluation
• Flycheck - Syntax checking with lintr and custom styler checker
• LSP Mode - Language Server Protocol with R languageserver
• Company - Smart code completion
• Vertico/Consult - Modern completion framework
• Magit - Visual Git interface
• Projectile - Project management
• Which-Key - Keybinding discovery
• Yasnippet - Code snippets
• Quarto/Polymode - Quarto document support
• AUCTeX - LaTeX integration
• Org Mode - Enhanced org-mode
• Citar - Citation management

Helper Scripts (~/.emacs.d/bin/)

• r-styler-check.R - External Flycheck checker for styler
• export-gui-path.sh - PATH exporter for macOS GUI Emacs

Documentation

• guides/TUTORIAL.md - Complete user guide
• guides/CHEAT-SHEET.md - Quick keybinding reference
• guides/TROUBLESHOOTING.md - Problem solving guide
• tests/TEST-CHECKLIST.md - Verification checklist

Test Files

• tests/test-features.R - Interactive feature testing
• tests/test-roxygen.R - Roxygen generation testing

🌟 Workflow Integration

emacs-r-devkit integrates seamlessly with:

• Terminal Workflow - Use with rtest, rdoc, rcheck aliases
• Claude Code - AI-powered development assistance
• zsh-environment - Modern shell with development tools
• r-package-development - Complete R workflow automation

💻 Development Workflow

# 1. Open R package
cd ~/R-packages/active/mypackage
emacs .

# 2. Edit code in Emacs
# - Auto-completion
# - Real-time error checking
# - Roxygen documentation
# - Auto-formatting on save

# 3. Test interactively in R console
# M-x R
# C-RET to send code

# 4. Validate in terminal
rtest          # Run tests
rdoc           # Build documentation
rcheck         # R CMD check

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Ways to Contribute

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features or improvements
• 📝 Improve documentation
• 🔧 Submit pull requests

📋 Requirements

System

• macOS 12.0+ (Monterey or later)
• Emacs 27.1+ (30.0+ recommended)
• R 4.0+
• Git 2.0+

Required R Packages

install.packages(c(
  "devtools",
  "usethis",
  "roxygen2",
  "testthat",
  "lintr",
  "styler"
))

Optional R Packages

install.packages(c(
  "languageserver",  # LSP support
  "s7",              # S7 OOP system
  "covr",            # Test coverage
  "pkgdown",         # Package websites
  "remotes"          # Remote packages
))

🔍 Verification

After installation, verify everything works:

# Run automated checks
./check-dependencies.sh

# Open test file in Emacs
emacs tests/test-features.R

# Follow tests/TEST-CHECKLIST.md for comprehensive testing

📖 Learning Resources

• Emacs Speaks Statistics (ESS)
• R Packages Book
• Material for MkDocs
• GNU Emacs Manual

🐛 Troubleshooting

Having issues? Check:

1. Troubleshooting Guide - Common problems and solutions
2. GitHub Issues - Known issues and discussions
3. Dependency Checker - Run ./check-dependencies.sh
4. Messages Buffer - In Emacs: ⌃ h e

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• GNU Emacs - The extensible text editor
• ESS - Emacs Speaks Statistics
• Material for MkDocs - Documentation theme
• R Project - Statistical computing

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: data-wise.github.io/emacs-r-devkit

---

Made with ❤️ for the R development community

⭐ Star this repo if you find it useful!