update development setup with submodule, makefile, and docs

2025-09-27 14:57:33 +02:00
parent 9c922caf53
commit 8313fa33fb
6 changed files with 238 additions and 22 deletions
--- a/.gitmodules
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "src"]
+	path = src
+	url = https://codeberg.org/uzu/strudel.git
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -202,6 +202,15 @@ $: sound("hh*8").sometimes(rev).often(x => x.gain(0.5))
 - **Use NixOS shells/dev environments**: Always prefer Nix-based development environments for reproducible builds
 - **Current NixOS version**: 25.05

+#### Git Submodules
+
+The Strudel codebase is managed as a git submodule in the 'src' directory. To work with the codebase:
+
+1. Initialize submodules: `make submodules-init`
+2. Update submodules: `make submodules-update`
+
+This ensures the correct version of the Strudel repository is checked out and kept in sync.
+
 #### Nix Development Shell

 Use the following `flake.nix` for Strudel development:
@@ -257,9 +266,12 @@ Use the following `flake.nix` for Strudel development:
   ```

 **Option 2: Using Makefile (recommended)**
-The Makefile provides convenient shortcuts for common development tasks:
+The Makefile provides convenient shortcuts for common development tasks. First, ensure submodules are initialized:

 ```bash
+# Initialize and update submodules
+make update
+
 # Install dependencies
 make install

--- a/55
+++ b/55
@@ -1,59 +1,72 @@
 # Makefile for Strudel development
 # This Makefile acts as a proxy for nix develop commands

-.PHONY: help install dev build test lint format check clean shell
+.PHONY: help install dev build test lint format check clean shell submodules-init submodules-update update

 # Default target
 help:
 	@echo "Strudel Development Makefile"
 	@echo ""
 	@echo "Available targets:"
-	@echo "  help     - Show this help message"
-	@echo "  install  - Install dependencies (pnpm install)"
-	@echo "  dev      - Start development server (pnpm dev)"
-	@echo "  build    - Build the project (pnpm build)"
-	@echo "  test     - Run tests (pnpm test)"
-	@echo "  lint     - Run linter (pnpm lint)"
-	@echo "  format   - Format code (pnpm codeformat)"
-	@echo "  check    - Run all checks (pnpm check)"
-	@echo "  clean    - Clean build artifacts"
-	@echo "  shell    - Enter Nix development shell"
+	@echo "  help              - Show this help message"
+	@echo "  update            - Initialize and update git submodules"
+	@echo "  install           - Install dependencies (pnpm install)"
+	@echo "  dev               - Start development server (pnpm dev)"
+	@echo "  build             - Build the project (pnpm build)"
+	@echo "  test              - Run tests (pnpm test)"
+	@echo "  lint              - Run linter (pnpm lint)"
+	@echo "  format            - Format code (pnpm codeformat)"
+	@echo "  check             - Run all checks (pnpm check)"
+	@echo "  clean             - Clean build artifacts"
+	@echo "  shell             - Enter Nix development shell"
 	@echo ""
 	@echo "All commands run within the Nix development environment."

 # Install dependencies
 install:
-	nix develop --command pnpm install
+	nix develop --command "cd src && pnpm install"

 # Start development server
 dev:
-	nix develop --command pnpm dev
+	nix develop --command "cd src && pnpm dev"

 # Build the project
 build:
-	nix develop --command pnpm build
+	nix develop --command "cd src && pnpm build"

 # Run tests
 test:
-	nix develop --command pnpm test
+	nix develop --command "cd src && pnpm test"

 # Run linter
 lint:
-	nix develop --command pnpm lint
+	nix develop --command "cd src && pnpm lint"

 # Format code
 format:
-	nix develop --command pnpm codeformat
+	nix develop --command "cd src && pnpm codeformat"

 # Run all checks
 check:
-	nix develop --command pnpm check
+	nix develop --command "cd src && pnpm check"

 # Clean build artifacts
 clean:
-	nix develop --command pnpm clean 2>/dev/null || true
-	rm -rf node_modules/.cache 2>/dev/null || true
-	rm -rf dist 2>/dev/null || true
+	nix develop --command "cd src && pnpm clean 2>/dev/null || true"
+	rm -rf src/node_modules/.cache 2>/dev/null || true
+	rm -rf src/dist 2>/dev/null || true
+
+# Initialize submodules
+submodules-init:
+	git submodule init
+
+# Update submodules
+submodules-update:
+	git submodule update
+
+# Initialize and update submodules
+update:
+	git submodule init && git submodule update

 # Enter Nix development shell
 shell:
--- a/README.md
+++ b/README.md
@@ -0,0 +1,126 @@
+# Strudel Development Environment
+
+A Nix-based development setup for [Strudel](https://strudel.cc/), a JavaScript-based live coding environment for algorithmic music composition and performance, inspired by TidalCycles.
+
+## Overview
+
+This repository provides a reproducible development environment for Strudel using Nix and includes the Strudel codebase as a git submodule. It includes:
+
+- **Nix Flake**: Reproducible development environment with Node.js 20, pnpm, and git
+- **Makefile**: Convenient shortcuts for common development tasks
+- **Git Submodule**: Tracks the official Strudel repository in the `src/` directory
+- **Agent Guidelines**: Comprehensive guidelines for AI assistants working with Strudel
+
+## Prerequisites
+
+- [Nix](https://nixos.org/download.html) package manager (version 2.4+ recommended)
+- Git
+
+## Quick Start
+
+1. **Clone this repository**:
+   ```bash
+   git clone <this-repo-url>
+   cd strudel
+   ```
+
+2. **Initialize and update submodules**:
+   ```bash
+   make submodules-init submodules-update
+   ```
+
+3. **Enter the development environment**:
+   ```bash
+   make shell
+   # or directly: nix develop
+   ```
+
+4. **Install dependencies**:
+   ```bash
+   make install
+   ```
+
+5. **Start the development server**:
+   ```bash
+   make dev
+   ```
+
+The Strudel REPL should now be available at `http://localhost:5173` (or similar, check the output).
+
+## Project Structure
+
+```
+strudel/
+├── src/                    # Strudel codebase (git submodule)
+├── AGENTS.md              # Guidelines for AI assistants
+├── Makefile               # Development shortcuts
+├── flake.nix              # Nix development environment
+├── flake.lock             # Nix flake lockfile
+└── README.md              # This file
+```
+
+## Development Workflow
+
+### Using Makefile (Recommended)
+
+The Makefile provides shortcuts for all common tasks:
+
+```bash
+make help              # Show all available targets
+make update            # Initialize and update git submodules
+make install           # Install dependencies
+make dev               # Start development server
+make build             # Build the project
+make test              # Run tests
+make lint              # Run linter
+make format            # Format code
+make check             # Run all checks
+make clean             # Clean build artifacts
+make shell             # Enter Nix development shell
+```
+
+### Direct Commands
+
+If you prefer direct commands, all operations run within the Nix environment:
+
+```bash
+# Enter shell
+nix develop
+
+# Install dependencies
+pnpm install
+
+# Start dev server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# etc.
+```
+
+## Contributing
+
+- Follow the guidelines in `AGENTS.md` for AI-assisted development
+- Use lowercase commit messages
+- Ensure all changes pass `make check`
+- Test your changes thoroughly
+
+## License
+
+The Strudel codebase in `src/` is licensed under the terms in `src/LICENSE`. This development environment setup is provided as-is for Strudel development.
+
+## Resources
+
+- [Strudel Official Website](https://strudel.cc/)
+- [Strudel Workshop](https://strudel.cc/workshop/)
+- [Strudel Git Repository](https://codeberg.org/uzu/strudel.git)
+- [NixOS](https://nixos.org/)
+
+## Troubleshooting
+
+- **Submodule issues**: Run `make update` to ensure the submodule is properly initialized
+- **Dependency issues**: Try `make clean && make install` to reinstall dependencies
+- **Nix issues**: Ensure Nix is installed and up-to-date
+
+For more help, refer to the [Strudel documentation](https://strudel.cc/) or check the `AGENTS.md` guidelines.</content>
--- a/flake.lock
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1758791193,
+        "narHash": "sha256-F8WmEwFoHsnix7rt290R0rFXNJiMbClMZyIC/e+HYf0=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "25e53aa156d47bad5082ff7618f5feb1f5e02d01",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
--- a/1
+++ b/1