From 035a280383ff4d651ee490e3cb4f9eff4362e414 Mon Sep 17 00:00:00 2001 From: thinktankmachine Date: Wed, 6 Aug 2025 15:38:06 +1000 Subject: [PATCH] Update documentation with comprehensive usage guide and improved update script --- README.md | 363 ++++++++++++++++++++++++++++++------------ update-cursor-hash.sh | 151 +++++++++++++++--- 2 files changed, 392 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 20a7e28..0b1455b 100644 --- a/README.md +++ b/README.md @@ -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="" + + # 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" + + # 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]"; + }} "$@" +''; +``` -### Development Environment +### Adding Additional Packages -The flake includes: +To add more development tools, edit `home.nix`: -- **Languages**: Node.js 20, Python 3, Rust -- **Tools**: Git, ripgrep, fd, bat, exa, fzf, tmux -- **Shell**: Zsh with Starship prompt -- **Terminal**: Alacritty - -### Customization - -To customize the configuration: - -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` +```nix +home.packages = with pkgs; [ + # Existing packages... + + # 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 \ No newline at end of file +- [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 \ No newline at end of file diff --git a/update-cursor-hash.sh b/update-cursor-hash.sh index fb98032..733272d 100755 --- a/update-cursor-hash.sh +++ b/update-cursor-hash.sh @@ -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") + +if [[ -z "$HASH" ]]; then + print_error "Failed to get hash" + exit 1 +fi -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" +print_success "SHA256 hash: $HASH" 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!" +# 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 - echo "Please update home.nix manually with the hash above." -fi \ No newline at end of file + 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!" \ No newline at end of file