Felix Roos
GitHub
commit
fc71d349ed
6 changed files with 437 additions and 54 deletions
|
|
@ -73,9 +73,9 @@ export const SIDEBAR: Sidebar = {
|
|||
],
|
||||
Development: [
|
||||
{ text: 'REPL', link: 'technical-manual/repl' },
|
||||
{ text: 'Packages', link: 'technical-manual/packages' },
|
||||
{ text: 'Docs', link: 'technical-manual/docs' },
|
||||
{ text: 'Testing', link: 'technical-manual/testing' },
|
||||
// { text: 'Packages', link: 'technical-manual/packages' },
|
||||
// { text: 'Internals', link: 'technical-manual/internals' },
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -7,5 +7,79 @@ layout: ../../layouts/MainLayout.astro
|
|||
|
||||
You can use Strudel even without a network! When you first visit the [Strudel REPL](strudel.tidalcycles.org/),
|
||||
your browser will download the whole web app including documentation.
|
||||
When the download is finished (<1MB), you can visit the website even when offline,
|
||||
getting the downloaded website instead of the online one.
|
||||
|
||||
When the site gets updated, your browser will download that update on the next online visit.
|
||||
When an update is available, the site will refresh after the download is finished.
|
||||
|
||||
This works because Strudel is implemented as progessive web app (using [Vite PWA](https://vite-pwa-org.netlify.app/)).
|
||||
|
||||
## Samples
|
||||
|
||||
While the browser will download the app itself, samples are only downloaded when you're actively using them.
|
||||
So to make sure a specific set of samples is available when offline, just use them.
|
||||
Also, only samples from these domains will be cached for offline use:
|
||||
|
||||
- `https://raw.githubusercontent.com/*` for samples uploaded to github
|
||||
- `https://freesound.org/*` / `https://cdn.freesound.org/*` for freesound
|
||||
- `https://shabda.ndre.gr/.*` for shabda
|
||||
|
||||
## Inspecting / Clearing Cache
|
||||
|
||||
You can view all cached files in your browser.
|
||||
|
||||
### Firefox
|
||||
|
||||
- Open the Developer Tools (`Tools > Web Developer > Web Developer Tools`)
|
||||
- go to `Storage` tab and expand `Cache Storage > https://strudel.tidalcycles.org`.
|
||||
- or go to the `Application` tab and view the latest updates in `Service Workers`
|
||||
|
||||
### Chromium based Browsers
|
||||
|
||||
- Open Developer Tools (`Right Click > Inspect`)
|
||||
- go to the `Application` tab
|
||||
- view downloaded files under `Cache > Cache Storage`
|
||||
- view the latest updates in `Service Workers`
|
||||
|
||||
## Strudel Standalone App
|
||||
|
||||
You can also install Strudel as a standalone app on most devices.
|
||||
A standalone app has its own desktop / homescreen icon and launches in a separate window,
|
||||
without the browser ui.
|
||||
|
||||
<figure>
|
||||
<img src="./pwa/strudel-macos.png" alt="Strudel on MacOS" />
|
||||
<figcaption>Strudel on MacOS</figcaption>
|
||||
</figure>
|
||||
|
||||
### Desktop
|
||||
|
||||
With a chromium based browser:
|
||||
|
||||
1. go to the [Strudel REPL](strudel.tidalcycles.org/).
|
||||
2. on the right of the adress bar, click `install Strudel REPL`
|
||||
3. the REPL should now run as a standalone chromium app
|
||||
|
||||
Without a chromium based browser, you can use [nativefier](https://github.com/nativefier/nativefier) to generate a desktop app:
|
||||
|
||||
1. make sure you have NodeJS installed
|
||||
2. run `npx nativefier strudel.tidalcycles.org`
|
||||
|
||||
<figure>
|
||||
<img src="./pwa/strudel-linux.png" alt="Strudel on Linux" />
|
||||
<figcaption>Strudel on Linux</figcaption>
|
||||
</figure>
|
||||
|
||||
### iOS
|
||||
|
||||
1. open to the [Strudel REPL](strudel.tidalcycles.org/) in safari
|
||||
2. press the share icon and tab `Add to homescreen`
|
||||
3. You should now have a strudel app icon that opens the repl in full screen
|
||||
|
||||
### Android
|
||||
|
||||
1. open to the [Strudel REPL](strudel.tidalcycles.org/)
|
||||
2. Tab the install button at the bottom
|
||||
|
||||
Ok, what are [Patterns](/technical-manual/patterns) all about?
|
||||
|
|
|
|||
|
|
@ -5,75 +5,58 @@ layout: ../../layouts/MainLayout.astro
|
|||
|
||||
import { MiniRepl } from '../../docs/MiniRepl';
|
||||
|
||||
## Strudel Packages
|
||||
# Strudel Packages
|
||||
|
||||
The [strudel repo](github.com/tidalcycles/strudel) is organized into packages, using [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).
|
||||
Publishing packages is done with [lerna](https://lerna.js.org/).
|
||||
The [strudel repo](github.com/tidalcycles/strudel) is organized as a monorepo, containing multiple npm packages.
|
||||
The purpose of the multiple packages is to
|
||||
|
||||
There are different packages for different purposes. They..
|
||||
- organize the codebase into more modular, encapsulated pieces
|
||||
- be able to opt out of certain functionalities
|
||||
- keep the dependencies of the core packages small
|
||||
|
||||
- split up the code into smaller chunks
|
||||
- can be selectively used to implement some sort of time based system
|
||||
## Overview
|
||||
|
||||
[See the latest published packages on npm](https://www.npmjs.com/search?q=%40strudel.cycles).
|
||||
Here is an overview of all the packages:
|
||||
|
||||
### Important bits
|
||||
### Essential Packages
|
||||
|
||||
- The [root package.json](https://github.com/tidalcycles/strudel/blob/main/package.json) specifies `packages/*` as `workspaces`
|
||||
- Each folder in `packages` comes with its own `package.json`, defining a package name of the format `@strudel.cycles/<name>`
|
||||
- Running `npm i` from the root folder will symlink all packages to the `node_modules` folder, e.g. `node_modules/@strudel.cycles/core` symlinks `packages/core`
|
||||
- These symlinks allow importing the packages with their package name, instead of a relative path, e.g. `import { seq } from '@strudel.cycles/core'`, instead of `import { seq } from '../core/`.
|
||||
This works because the [bare module import](https://vitejs.dev/guide/features.html#npm-dependency-resolving-and-pre-bundling) `@strudel.cycles/core` is resolved to `node_modules/@strudel.cycles/core`.
|
||||
In a project that installs the published packages from npm, these imports will still work, whereas relative ones might not.
|
||||
- When a strudel package is importing from another strudel package, the package that is imported from should be listed in the `dependencies` field of the `package.json`.
|
||||
For example, [@strudel.cycles/mini lists `@strudel.cycles/core` as a dependency](https://github.com/tidalcycles/strudel/blob/main/packages/mini/package.json).
|
||||
- In development, files in any package can be changed and saved to instantly update the dev server via [hot module replacement](https://vitejs.dev/guide/features.html#hot-module-replacement)
|
||||
- To publish packages, `npx lerna publish` will check which packages were changed since the last publish and publish only those.
|
||||
The version numbers in the dependencies of each packages will be updated automatically to the latest version.
|
||||
These package are the most essential. You might want to use all of those if you're using strudel in your project:
|
||||
|
||||
### Building & Publishing
|
||||
- [core](https://github.com/tidalcycles/strudel/tree/main/packages/core#strudelcyclescore): tidal pattern engine with core primitives
|
||||
- [mini](https://github.com/tidalcycles/strudel/tree/main/packages/mini#strudelcyclesmini): mini notation parser + core bindings
|
||||
- [transpiler](https://github.com/tidalcycles/strudel/tree/main/packages/transpiler#strudelcyclestranspiler): user code transpiler. syntax sugar + highlighting
|
||||
|
||||
Currently, all packages are only published as ESM with vite flavour.
|
||||
To build standardized ESM and CJS files, a `vite.config.js` like that is needed:
|
||||
### Language Extensions
|
||||
|
||||
```js
|
||||
import { defineConfig } from 'vite';
|
||||
import { dependencies } from './package.json';
|
||||
import { resolve } from 'path';
|
||||
These packages extend the pattern language by specific functions
|
||||
|
||||
// https://vitejs.dev/config/
|
||||
export default defineConfig({
|
||||
plugins: [],
|
||||
build: {
|
||||
lib: {
|
||||
entry: resolve(__dirname, 'index.mjs'),
|
||||
formats: ['es', 'cjs'],
|
||||
fileName: (ext) => ({ es: 'index.mjs', cjs: 'index.js' }[ext]),
|
||||
},
|
||||
rollupOptions: {
|
||||
external: [...Object.keys(dependencies)],
|
||||
},
|
||||
target: 'esnext',
|
||||
},
|
||||
});
|
||||
```
|
||||
- [tonal](https://github.com/tidalcycles/strudel/tree/main/packages/tonal): tonal functions for scales and chords
|
||||
- [xen](https://github.com/tidalcycles/strudel/tree/main/packages/xen): microtonal / xenharmonic functions
|
||||
|
||||
This will build `index.mjs` (ESM) and `index.js` (CJS) to the dist folder.
|
||||
### Outputs
|
||||
|
||||
### What's the main file?
|
||||
These packages provide bindings for different ways to output strudel patterns:
|
||||
|
||||
Currently, each package uses the unbundled `index.mjs` as its main file, which must change for the published version.
|
||||
There are 2 ways to handle this:
|
||||
- [webaudio](https://github.com/tidalcycles/strudel/tree/main/packages/webaudio#strudelcycleswebaudio): the default webaudio output
|
||||
- [osc](https://github.com/tidalcycles/strudel/tree/main/packages/osc#strudelcyclesosc): bindings to communicate via OSC
|
||||
- [midi](https://github.com/tidalcycles/strudel/tree/main/packages/midi#strudelcyclesmidi): webmidi bindings
|
||||
- [csound](https://github.com/tidalcycles/strudel/tree/main/packages/csound#strudelcyclescsound): csound bindings
|
||||
- [soundfonts](https://github.com/tidalcycles/strudel/tree/main/packages/serial#strudelcyclessoundfonts): Soundfont support
|
||||
- [serial](https://github.com/tidalcycles/strudel/tree/main/packages/serial#strudelcyclesserial): webserial bindings
|
||||
|
||||
1. `main` = `dist/index.js`, `module` = `dist/index.mjs`. The built files are used. This means that changing a source file won't take effect in the dev server without a rebuild.
|
||||
2. Use different `package.json` files for dev vs publish. So the unbuilt `index.mjs` could be used in dev, while the built files can be used when publishing.
|
||||
### Others
|
||||
|
||||
Option 1 could be done with [workspace watching](https://lerna.js.org/docs/features/workspace-watching), although it might make the dev server less snappy..
|
||||
Option 2 can be done by [publishing just the dist folder and copying over the `package.json` file](https://stackoverflow.com/questions/37862712/how-to-publish-contents-only-of-a-specific-folder).
|
||||
Sadly, [this does not fit into how lerna works](https://github.com/lerna/lerna/issues/91).
|
||||
- [embed](https://github.com/tidalcycles/strudel/tree/main/packages/embed#strudelcyclesembed): embeddable REPL web component
|
||||
- [react](https://github.com/tidalcycles/strudel/tree/main/packages/react#strudelcyclesreact): react hooks and components for strudel
|
||||
|
||||
https://github.com/changesets/changesets
|
||||
### No Longer Maintained
|
||||
|
||||
https://turbo.build/repo/docs/handbook/publishing-packages/versioning-and-publishing
|
||||
- [eval](https://github.com/tidalcycles/strudel/tree/main/packages/eval): old code transpiler
|
||||
- [tone](https://github.com/tidalcycles/strudel/tree/main/packages/tone#strudelcyclestone): bindings for Tone.js instruments and effects
|
||||
- [webdirt](https://github.com/tidalcycles/strudel/tree/main/packages/webdirt): webdirt bindings, replaced by webaudio package
|
||||
|
||||
https://pnpm.io/workspaces
|
||||
## Tools
|
||||
|
||||
- [pnpm workspaces](https://pnpm.io/)
|
||||
- Publishing packages is done with [lerna](https://lerna.js.org/).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue