|
| 1 | +--- |
| 2 | +name: edg-agent-temp-files |
| 3 | +description: >- |
| 4 | + Where agents put temporary files and directories (scratchpad, the project's |
| 5 | + .tmp/agent-* directory, or the container's /tmp), how to share them with the |
| 6 | + docker container via edg-exec, and how to run edgy ad hoc with --runs-dir |
| 7 | + (and a scratch EDG_TEST_HOME) instead of edg-docker-test. Use when creating |
| 8 | + scratch inputs or outputs, running throwaway tests or recordings, or cleaning |
| 9 | + up temporary state. |
| 10 | +--- |
| 11 | + |
| 12 | +# Temporary state and the docker boundary |
| 13 | + |
| 14 | +Tools run either on the host or in the docker container (`edg-exec`). The |
| 15 | +container sees **only the project root**, mounted at `/edg/workspace`; the host |
| 16 | +`/tmp` and your scratchpad are not visible to it. Project root = directory |
| 17 | +containing `src/cfe.c` and `dev_tools/`. |
| 18 | + |
| 19 | +## Where to put temporary state |
| 20 | + |
| 21 | +| Need | Put it in | Notes | |
| 22 | +| --- | --- | --- | |
| 23 | +| Host-only (scripts, outputs of host tools) | your scratchpad directory | no permission prompts | |
| 24 | +| Shared with the container | `<root>/.tmp/agent-<purpose>` | seen as `/edg/workspace/.tmp/agent-<purpose>`; `.tmp/` is gitignored | |
| 25 | +| Only needed inside the container | the container's `/tmp` | ephemeral, nothing is left on the host | |
| 26 | + |
| 27 | +- Everything you create in `.tmp/` **must** be named `agent-<purpose>` (the |
| 28 | + rest of `.tmp/` is the user's host-to-docker bridge; see `.tmp/README.md`). |
| 29 | +- Do not use `build/`, `tests/runs/`, or the host `/tmp` for scratch state. |
| 30 | +- Files created in the container are owned by the host user, so they are |
| 31 | + directly usable from the host. |
| 32 | + |
| 33 | +## edg-exec rules |
| 34 | + |
| 35 | +- Run `edg-exec` from the project root (the current directory is mounted as |
| 36 | + `/edg/workspace`). |
| 37 | +- `edg-exec` joins its arguments with spaces and **does not preserve |
| 38 | + quoting**: `edg-exec -- sh -c '. env.sh; cmd'` runs `sh -c .` and drops the |
| 39 | + rest. Pass a compound command as ONE quoted string: |
| 40 | + |
| 41 | + ```bash |
| 42 | + edg-exec -- "mkdir -p .tmp/agent-foo && echo hi > .tmp/agent-foo/x" |
| 43 | + edg-exec --dry-run -- "..." # shows exactly what the container will run |
| 44 | + ``` |
| 45 | + |
| 46 | +- `edgy` and the other `dev_tools/bin` tools are on the container `PATH`. |
| 47 | + |
| 48 | +## Running edgy outside the standard workflow |
| 49 | + |
| 50 | +`edg-docker-test` is for the standard front-end change workflow, where the |
| 51 | +user wants results kept in `tests/runs/` (see **edg-cpfe-build-test**). For |
| 52 | +anything else (experiments, verification of tooling, comparisons), run `edgy` |
| 53 | +with `--runs-dir` so nothing lands in `tests/runs/`: |
| 54 | + |
| 55 | +```bash |
| 56 | +# In docker: results appear on the host under .tmp/agent-foo/runs/<timestamp>/ |
| 57 | +edg-exec -- ". build/gcc/environment.sh && edgy --runs-dir=/edg/workspace/.tmp/agent-foo/runs regressions/foo.sft.cpp" |
| 58 | +``` |
| 59 | + |
| 60 | +- `. build/<dir>/environment.sh` provides `CPFE`/`CPFE_CP`, which `edgy` uses |
| 61 | + to find the front end (use the build directory you are testing). The default |
| 62 | + configs need both `cpfe` and `cpfe-cp` built; `-c edg_x86_64` runs the C |
| 63 | + config alone. |
| 64 | +- Use an **absolute** container path for `--runs-dir`. `edgy` copies the front |
| 65 | + end under the runs directory and a relative path breaks tools that change |
| 66 | + directory (e.g. `cpfe-cp-gen-be` fails with "No such file or directory"). |
| 67 | +- Host-side tools that take `--runs-dir` (e.g. `edg-rematerialize-test-run`) |
| 68 | + have no docker constraint: point them at the scratchpad. |
| 69 | +- If `edg-docker-test` is still used for a throwaway run, pass |
| 70 | + `--discard-test-results` (results stay in the container's `/tmp`). |
| 71 | + |
| 72 | +## Scratch test home (for `-W` and other mutating experiments) |
| 73 | + |
| 74 | +`edg-docker-test` does not forward a host `EDG_TEST_HOME`, but setting it |
| 75 | +**inside** the container command works. Build a small test home and point at |
| 76 | +it; never run `-W` against the real tree: |
| 77 | + |
| 78 | +```bash |
| 79 | +H=.tmp/agent-foo/home |
| 80 | +mkdir -p $H/tests |
| 81 | +cp -r tests/.edgy $H/.edgy |
| 82 | +cp -r tests/expectations $H/expectations |
| 83 | +cp -r tests/tests/<suite> $H/tests/<suite> # only the suites you need |
| 84 | +CMD='. build/gcc/environment.sh && EDG_TEST_HOME=/edg/workspace/.tmp/agent-foo/home edgy --runs-dir=/edg/workspace/.tmp/agent-foo/runs <suite>/<test>' |
| 85 | +edg-exec -- "$CMD" # read-only first: logs must land under .tmp/agent-foo |
| 86 | +edg-exec -- "${CMD/edgy /edgy -W }" # then record (expectations and .rto files in the scratch home only) |
| 87 | +``` |
| 88 | + |
| 89 | +Check `git status --short tests` and that `tests/runs/` did not gain an entry. |
| 90 | + |
| 91 | +## Cleanup |
| 92 | + |
| 93 | +- Remove the `.tmp/agent-*` paths **you created** in a batch step as the LAST |
| 94 | + step before reporting results to the user (not after each sub-task), in ONE |
| 95 | + command that lists them (one approval instead of many): |
| 96 | + |
| 97 | + ```bash |
| 98 | + rm -rf .tmp/agent-foo .tmp/agent-bar |
| 99 | + ``` |
| 100 | + |
| 101 | +- Never glob other entries, never remove non-`agent-` names in `.tmp/`, and |
| 102 | + do not delete `tests/runs/` content (it is gitignored and may be the user's). |
| 103 | +- Say in the final summary what you created and removed. |
0 commit comments