127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# 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>
|