---
feature_story: FS_29_54_67_86
feature_title: project `dir_structure`
feature_status: TEST
---

This features describes the directory structure (a convention):
*   which `argrelay` uses for itself
*   which should be used for integration projects based on `argrelay` (to make scripts re-use-able)

See also `TopDir` enum.

To make it unambiguous that path is relative to project root dir,
it is referred to as `argrelay_dir` in scripts and indicated as `@/` in docs and comments,
for example: `@/exe/bootstrap_env.bash`.

Every script knows its relative position to `argrelay_dir` (or `@/`) to locate it.

Note that project root may or may not match repo root (e.g. Git):
*   it does for `argrelay` itself
*   but it may not for `argrelay`-based projects

```
@                 # project root
│
...
├── docs          # Documentation, notes, etc.
├── src           # Prod code
├── tests         # Test code
...
├── conf          # Git-ignored dir for all configuration files specific to the target environment.
│                 # Normally, `@/conf/` dir is a symlink to one of the sub-dirs under `@/dst/`,
│                 # if target environment configurations is decided to be stored in the same repo.
├── dst           # Target environment configurations (dst = "destination") - see also `@/conf/` dir.
│
├── data          # Files with various static data in different formats.
...
├── exe           # Executable artifacts which should NOT be accessible via `PATH`.
├── bin           # Executable artifacts which should be accessible via `PATH`.
...
├── var           # State files (e.g. PID files for running server, generated data, lock files, etc.).
...
├── tmp           # Git-ignored dir for disposable files (e.g. downloads).
├── drafts        # Git-ignored dir to stash files without committing them (yet).
├── dist          # Git-ignored dir for files generated by Python tools.
├── build         # Git-ignored dir for files generated by Python tools.
...
```

# `@/exe/`

Dir `@/exe/` contains immediately executable files.

# `@/conf/`

Dir `@/conf/` contains configuration files specific to target installation environment.

Normally, it is a symlink.

The symlink itself is not supposed to be version controlled by this repo, but the dir it points to can be:
*   one of `@/dst/*` dirs under the same repo
*   any other dir

In practice, to keep config under version control within the same repo, `@/conf/` can be a symlink which
points to different version controlled dir (see sub-dirs under `@/dst/`) depending on the target installation environment.

To avoid being detected as modified when target installation environment changes, this `@/conf/` symlink is not committed.

This path is the default (lowest priority) - see [`FS_16_07_78_84.conf_dir_priority.md`][FS_16_07_78_84.conf_dir_priority.md].

# `@/dst/`

This dir contains sub-dirs with config files for multiple target environments.

For example:
*   Dir `@/dst/` may contain sub-dirs: `@/dst/target_env_a` and `@/dst/target_env_b`.
*   When the project is installed to environment `target_env_a`, `@/conf/` should be a symlink to `@/dst/target_env_a`.
*   When the project is installed to environment `target_env_b`, `@/conf/` should be a symlink to `@/dst/target_env_b`.

# `@/exe/bootstrap_env.bash`

See FS_85_33_46_53 `bootstrap_env`.

# `@/exe/dev_shell.bash`

See FS_58_61_77_69 `dev_shell`.

# `@/conf/dev_shell_env.bash`

It is used by `@/exe/dev_shell.bash`.

[FS_16_07_78_84.conf_dir_priority.md]: FS_16_07_78_84.conf_dir_priority.md
