diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..8b5d602 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "src"] + path = src + url = https://codeberg.org/uzu/strudel.git diff --git a/AGENTS.md b/AGENTS.md index e69d25d..2719ced 100644 --- 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 diff --git a/Makefile b/Makefile index a9d547b..94702ce 100644 --- a/Makefile +++ b/Makefile @@ -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: diff --git a/README.md b/README.md new file mode 100644 index 0000000..87bea39 --- /dev/null +++ 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 + 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. diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..2ad6c0b --- /dev/null +++ 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 +} diff --git a/src b/src new file mode 160000 index 0000000..e1629e8 --- /dev/null +++ b/src @@ -0,0 +1 @@ +Subproject commit e1629e8383e791b1530a69a398cccf781ae8f70e