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/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>