add missing doc

[?]

Jan 25, 2023, 4:28 PM

7ZIFAEBRSUYG3HBD6NIZYKUNAZZ7J65RYHWZVRHNLNKGHCZGCVHAC

Dependencies

[2] TNRO6KLZ new live app

Change contents

file addition: representation.md (----------)

[2.2]

# The on-disk representation of freewheeling apps

When you start up a freewheeling app, you'll see a directory printed out in
the parent terminal (always launch it from a terminal window):

```
new edits will go to /home/...
```

When editing such an app using the driver (see [README.md](README.md)), new
definitions will go into this directory. Let's call it `$SAVE_DIR` in the rest
of this doc.

It is always safe to move such definitions into this repo. (We'll call it `.`
in the rest of this doc.) You'll want to do this if you're sharing them with
others, and it's also helpful if the driver crashes on your app. Moving
definitions will never, ever change app behavior.

```sh
$ mv -i $SAVE_DIR/[0-9]* . # should never clobber any existing files
$ mv $SAVE_DIR/head . # expected to clobber the existing file
```

Try looking inside the `head` file with a text editor. It'll contain a number,
the current version of the _manifest_ for this app. For example:

```
478
```

This means the current state of the app is in a file called `0478-fwmanifest`.
If you moved the files you should see such a file in `.`. If you open this
file, you'll see a JSON table from definition names to version ids. For
example:

```
{ "a": 273, "b": 478}
```

This means the current definition of `a` is in `0273-a` and of `b` in
`0478-b`.

Poking around these files gets repetitive, so there's a tool to streamline
things:

```
lua tools/stitch-live.lua 0478-fwmanifest
```

`stitch-live.lua` takes a manifest file as its argument, and prints out all
the definitions that make up the app at that version.

To compare two versions of the app, use `stitch-live.lua` to copy the
definitions in each into a separate file, and use a file comparison tool (e.g.
`diff`) to compare the two files.