Olivier/cursor-nixos-flake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation with comprehensive usage guide and improved update script

Browse Source
This commit is contained in:
thinktankmachine
2025-08-06 15:38:06 +10:00
parent 9d0bcd6aed
commit 035a280383
2 changed files with 392 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+256 -101
View File
@@ -1,165 +1,320 @@
# Cursor Flake
# Cursor NixOS Flake
A NixOS flake that provides a complete development environment with Cursor 1.3.9 (AI-first code editor) as an AppImage.
A NixOS flake that provides Cursor 1.3.9 (AI-first code editor) as an AppImage with enhanced compatibility for NixOS systems.
## Features
- **Cursor 1.3.9**: Latest version of the AI-first code editor
- **AppImage Support**: Full AppImage compatibility with proper desktop integration
- **Development Tools**: Complete development environment with Node.js, Python, Rust, and more
- **Enhanced AppImage Support**: Optimized for NixOS with proper library paths and environment setup
- **Easy Integration**: Can be used as a standalone system or integrated into existing NixOS flakes
- **Development Tools**: Complete development environment with modern tools
- **Modern Shell**: Zsh with Starship prompt and useful aliases
- **Desktop Environment**: GNOME with essential utilities
- **Git Integration**: Pre-configured Git with modern defaults
## Prerequisites
## Quick Start
- NixOS system with flakes enabled
- At least 8GB RAM recommended
- 20GB free disk space
## Installation
### 1. Clone the Repository
### Option 1: Use as a Standalone System
```bash
# Clone the repository
git clone https://github.com/thinktankmachine/cursor-nixos-flake
cd cursor-nixos-flake
```
### 2. Update the SHA256 Hash (if needed)
The current configuration uses the working Cursor 1.3.9 download URL. If you need to update to a newer version, run:
```bash
./update-cursor-hash.sh
```
This will automatically update the hash in `home.nix` with the correct value.
### 3. Customize Configuration
Edit the following files to match your system:
- `configuration.nix`: System-wide settings
- `home.nix`: User-specific settings (change username from "liam" to your username)
- `hardware-configuration.nix`: Hardware-specific settings (run `nixos-generate-config` on your target system)
### 4. Build and Switch
```bash
# Build the configuration
sudo nixos-rebuild build --flake .#cursor-system
# Switch to the new configuration
# Build and switch to the configuration
sudo nixos-rebuild switch --flake .#cursor-system
```
### 5. First Boot Setup
### Option 2: Integrate into Existing NixOS Flake
After the first boot:
Add to your `/etc/nixos/flake.nix`:
1. Log in as the configured user
2. Cursor will be available in the applications menu
3. You can also launch it from the terminal with `cursor`
```nix
{
inputs = {
# ... your existing inputs
cursor-flake = {
url = "github:thinktankmachine/cursor-nixos-flake";
inputs.nixpkgs.follows = "nixpkgs";
inputs.home-manager.follows = "home-manager";
};
};
outputs = { nixpkgs, home-manager, cursor-flake, ... }: {
nixosConfigurations.your-system = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
# ... your existing modules
{
home-manager.users.your-username = { pkgs, ... }: {
home.packages = with pkgs; [
# ... your existing packages
] ++ [
# Add Cursor from the flake
cursor-flake.packages.x86_64-linux.cursor
];
};
}
];
};
};
}
```
Then rebuild:
```bash
sudo nix flake update
sudo nixos-rebuild switch --flake .#your-system
```
## Usage
After installation, Cursor will be available:
- **Applications Menu**: Look for "Cursor" in your desktop environment
- **Terminal**: Run `cursor` from any terminal
- **Command Line**: Use `cursor --version` to verify installation
## Updating Cursor
When a new version of Cursor is released, follow these steps to update the flake:
### Step 1: Find the New Download URL
1. Go to [Cursor's download page](https://cursor.sh/)
2. Find the Linux AppImage download link
3. Copy the URL (it will look like: `https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage`)
### Step 2: Update the Flake
1. **Update the URL in `home.nix`**:
```nix
# Find this section in home.nix
cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
# ... environment setup ...
# Run the AppImage with appimage-run
exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
url = "https://downloads.cursor.com/production/[NEW_HASH]/linux/x64/Cursor-[NEW_VERSION]-x86_64.AppImage";
sha256 = "OLD_HASH_HERE"; # This will be updated in the next step
}} "$@"
'';
```
2. **Update the SHA256 hash**:
```bash
# Run the update script (it will fetch the new URL and update the hash)
./update-cursor-hash.sh
```
3. **Test the build**:
```bash
# Test that the flake builds correctly
nix build .#packages.x86_64-linux.cursor
```
4. **Update your system**:
```bash
# If using standalone system
sudo nixos-rebuild switch --flake .#cursor-system
# If integrated into main system
cd /etc/nixos
sudo nix flake update
sudo nixos-rebuild switch --flake .#your-system
```
### Step 3: Verify the Update
```bash
# Check the version
cursor --version
# Launch Cursor to ensure it works
cursor
```
### Step 4: Commit and Push (Optional)
```bash
# Commit the changes
git add .
git commit -m "Update Cursor to version [NEW_VERSION]"
git push origin main
```
## Configuration
### Cursor Settings
### Customizing the Cursor Wrapper
The flake includes pre-configured Cursor settings in `~/.config/Cursor/User/settings.json`:
The Cursor AppImage wrapper in `home.nix` includes enhanced compatibility settings:
- Modern font (JetBrains Mono with ligatures)
- Dark theme
- Optimized editor settings
- Cursor AI features enabled
```nix
cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
# Set up environment for better AppImage compatibility
export APPDIR=""
export ARGV0=""
export OWD=""
### Development Environment
# Ensure proper library paths
export LD_LIBRARY_PATH="${pkgs.lib.makeLibraryPath [
pkgs.glib
pkgs.gtk3
pkgs.cairo
pkgs.pango
pkgs.atk
pkgs.gdk-pixbuf
pkgs.xorg.libX11
pkgs.xorg.libXcomposite
pkgs.xorg.libXcursor
pkgs.xorg.libXext
pkgs.xorg.libXfixes
pkgs.xorg.libXi
pkgs.xorg.libXrandr
pkgs.xorg.libXrender
pkgs.xorg.libXtst
pkgs.nss
pkgs.nspr
pkgs.dbus
pkgs.at-spi2-atk
pkgs.at-spi2-core
pkgs.mesa
pkgs.alsa-lib
]}:$LD_LIBRARY_PATH"
The flake includes:
# Run the AppImage with appimage-run
exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
url = "https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage";
sha256 = "[hash]";
}} "$@"
'';
```
- **Languages**: Node.js 20, Python 3, Rust
- **Tools**: Git, ripgrep, fd, bat, exa, fzf, tmux
- **Shell**: Zsh with Starship prompt
- **Terminal**: Alacritty
### Adding Additional Packages
### Customization
To add more development tools, edit `home.nix`:
To customize the configuration:
```nix
home.packages = with pkgs; [
# Existing packages...
1. **Add packages**: Edit `home.nix` and add to `home.packages`
2. **Change shell**: Modify the shell configuration in `home.nix`
3. **Update Cursor settings**: Edit the settings in `home.nix`
4. **System packages**: Add to `environment.systemPackages` in `configuration.nix`
# Add your packages here
nodejs_20
python3
rustc
cargo
# ... more packages
];
```
## Troubleshooting
### AppImage Issues
### Common Issues
If Cursor doesn't run properly:
#### 1. AppImage Won't Run
1. Check if AppImage support is enabled:
```bash
ls /proc/sys/fs/binfmt_misc/
```
**Symptoms**: `bwrap: Can't chdir to /etc/nixos: No such file or directory`
2. Reinstall AppImage support:
```bash
sudo nixos-rebuild switch --flake .#cursor-system
```
**Solution**: Run Cursor from your home directory, not from system directories:
```bash
cd ~
cursor
```
### Permission Issues
#### 2. Keymapping Errors
If you encounter permission issues:
**Symptoms**: `Error: Cannot find module './build/Debug/keymapping'`
1. Ensure the user is in the correct groups:
```bash
groups
```
**Solution**: These are cosmetic errors and don't prevent Cursor from working. The enhanced wrapper should reduce these errors.
2. Add user to additional groups if needed in `configuration.nix`
#### 3. Library Loading Issues
### Update Cursor
**Symptoms**: Various library-related errors
To update to a newer version of Cursor:
**Solution**: The enhanced wrapper includes all necessary libraries. If issues persist, try:
```bash
# Rebuild the system
sudo nixos-rebuild switch --flake .#your-system
1. Update the version number in `home.nix`
2. Update the download URL if needed
3. Update the SHA256 hash
4. Rebuild the system
# Clear AppImage cache
rm -rf ~/.cache/appimage-run/*
```
#### 4. Git Authentication Issues
**Symptoms**: `fatal: Authentication failed`
**Solution**: Ensure your remote uses SSH:
```bash
git remote set-url origin git@github.com:username/repo.git
```
### Testing the Flake
You can test the flake without affecting your system:
```bash
# Build the VM image
nix build .#nixosConfigurations.cursor-system.config.system.build.vm
# Run the VM
./result/bin/run-cursor-system-vm
```
## File Structure
```
cursor-flake/
├── flake.nix # Main flake definition
├── flake.nix # Main flake definition with outputs
├── configuration.nix # NixOS system configuration
├── home.nix # Home Manager user configuration
├── home.nix # Home Manager configuration with Cursor wrapper
├── hardware-configuration.nix # Hardware-specific settings
└── README.md # This file
├── update-cursor-hash.sh # Script to update Cursor hash
├── test-configuration.nix # Minimal test configuration
├── test-home.nix # Minimal test home configuration
└── README.md # This documentation
```
## Development
### Adding Features
1. **New packages**: Add to `home.packages` in `home.nix`
2. **System changes**: Modify `configuration.nix`
3. **User settings**: Update `home.nix` configuration
### Testing Changes
```bash
# Test the flake syntax
nix flake check
# Test building the package
nix build .#packages.x86_64-linux.cursor
# Test the full system
nix build .#nixosConfigurations.cursor-system.config.system.build.vm
```
## Contributing
1. Fork the repository
2. Create a feature branch
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Test the configuration
5. Submit a pull request
4. Test thoroughly: `nix flake check`
5. Commit: `git commit -m "Add feature description"`
6. Push: `git push origin feature-name`
7. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
This project is licensed under the MIT License.
## Support
For issues and questions:
1. Check the troubleshooting section
2. Search existing issues
3. Create a new issue with detailed information
- **Issues**: [GitHub Issues](https://github.com/thinktankmachine/cursor-nixos-flake/issues)
- **Discussions**: [GitHub Discussions](https://github.com/thinktankmachine/cursor-nixos-flake/discussions)
## Acknowledgments
- Cursor team for the excellent AI-first editor
- NixOS community for the amazing package management system
- Home Manager for user configuration management
- [Cursor](https://cursor.sh/) team for the excellent AI-first editor
- [NixOS](https://nixos.org/) community for the amazing package management system
- [Home Manager](https://github.com/nix-community/home-manager) for user configuration management
update-cursor-hash.sh
+136 -21
View File
@@ -1,32 +1,147 @@
#!/usr/bin/env bash
# Script to update the SHA256 hash for Cursor AppImage
# Run this script to get the correct hash and update home.nix
# This script helps you update the Cursor version and hash in the flake
set -e
echo "Fetching SHA256 hash for Cursor 1.3.9 AppImage..."
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Function to print colored output
print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Check if we're in the right directory
if [[ ! -f "home.nix" ]]; then
print_error "This script must be run from the cursor-flake directory"
exit 1
fi
print_info "Cursor AppImage Hash Updater"
echo ""
# Get current URL from home.nix
CURRENT_URL=$(grep -o 'https://downloads\.cursor\.com/[^"]*' home.nix | head -1)
if [[ -z "$CURRENT_URL" ]]; then
print_error "Could not find Cursor download URL in home.nix"
exit 1
fi
print_info "Current URL: $CURRENT_URL"
# Extract version from URL
CURRENT_VERSION=$(echo "$CURRENT_URL" | grep -o 'Cursor-[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 | sed 's/Cursor-//')
if [[ -z "$CURRENT_VERSION" ]]; then
print_warning "Could not extract version from URL, using 'unknown'"
CURRENT_VERSION="unknown"
fi
print_info "Current version: $CURRENT_VERSION"
echo ""
# Ask user if they want to update to a new version
read -p "Do you want to update to a new version? (y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
echo ""
print_info "To update to a new version:"
echo "1. Go to https://cursor.sh/"
echo "2. Download the Linux AppImage"
echo "3. Copy the download URL"
echo "4. Paste it below"
echo ""
read -p "Enter the new Cursor download URL: " NEW_URL
if [[ -z "$NEW_URL" ]]; then
print_error "No URL provided"
exit 1
fi
# Extract new version
NEW_VERSION=$(echo "$NEW_URL" | grep -o 'Cursor-[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 | sed 's/Cursor-//')
if [[ -z "$NEW_VERSION" ]]; then
print_warning "Could not extract version from new URL"
NEW_VERSION="unknown"
fi
print_info "New version: $NEW_VERSION"
# Update the URL in home.nix
sed -i "s|$CURRENT_URL|$NEW_URL|g" home.nix
print_success "Updated URL in home.nix"
URL_TO_HASH="$NEW_URL"
else
URL_TO_HASH="$CURRENT_URL"
fi
echo ""
print_info "Fetching SHA256 hash for AppImage..."
echo "URL: $URL_TO_HASH"
echo ""
# Get the hash
HASH=$(nix-prefetch-url https://downloads.cursor.com/production/54c27320fab08c9f5dd5873f07fca101f7a3e076/linux/x64/Cursor-1.3.9-x86_64.AppImage)
print_info "Downloading and computing hash (this may take a moment)..."
HASH=$(nix-prefetch-url "$URL_TO_HASH")
echo "SHA256 hash: $HASH"
echo ""
echo "Please update the hash in home.nix:"
echo "Replace the placeholder hash with:"
echo "sha256 = \"$HASH\";"
echo ""
echo "You can do this manually or run:"
echo "sed -i 's/sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";/sha256 = \"$HASH\";/' home.nix"
echo ""
# Optionally update the file automatically
read -p "Do you want to update home.nix automatically? (y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
sed -i "s/sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";/sha256 = \"$HASH\";/" home.nix
echo "Updated home.nix with the correct hash!"
else
echo "Please update home.nix manually with the hash above."
if [[ -z "$HASH" ]]; then
print_error "Failed to get hash"
exit 1
fi
echo ""
print_success "SHA256 hash: $HASH"
echo ""
# Find the current hash in home.nix
CURRENT_HASH=$(grep -o 'sha256 = "[^"]*"' home.nix | head -1 | sed 's/sha256 = "//;s/"//')
if [[ -z "$CURRENT_HASH" ]]; then
print_warning "Could not find current hash in home.nix"
print_info "Please manually update the hash in home.nix:"
echo "sha256 = \"$HASH\";"
else
print_info "Current hash: $CURRENT_HASH"
print_info "New hash: $HASH"
echo ""
if [[ "$CURRENT_HASH" == "$HASH" ]]; then
print_success "Hash is already up to date!"
else
# Update the hash in home.nix
sed -i "s/sha256 = \"$CURRENT_HASH\";/sha256 = \"$HASH\";/" home.nix
print_success "Updated hash in home.nix"
fi
fi
echo ""
print_info "Next steps:"
echo "1. Test the build: nix build .#packages.x86_64-linux.cursor"
echo "2. Update your system: sudo nixos-rebuild switch --flake .#your-system"
echo "3. Test Cursor: cursor --version"
echo ""
print_success "Hash update complete!"