---
feature_story: FS_85_33_46_53
feature_title: process to `bootstrap_env`
feature_status: TEST
---

See also FS_58_61_77_69 `dev_shell`.

# Purpose

This feature covers initial setup and upgrades of `argrelay`-integrated projects (their development environments).

This may overlap with functions from FS_36_17_84_44 check_env script.

The idea is to have a single `@/exe/bootstrap_env.bash` script which:
*   Loads `@/conf/python_env.conf.bash` (or prompts user if it does not exist) and inits `venv`.
*   Runs project-specific custom `@/exe/install_project.bash` (or prompts user if it does not exist).
*   Copies fresh version of itself from `argrelay` (for future use) and starts it to ensure it works.
*   Runs project-specific custom `@/exe/build_project.bash` (or prompts user if it does not exist).
*   Installs necessary configs and scripts.
*   Generates client and server executables under `@/bin/`.
*   Updates `@/conf/env_packages.txt`.
*   ...

Script `@/exe/bootstrap_env.bash` is supposed to be version controlled in the target project.
It is added to the target project repo so that it can be re-run during subsequent upgrades<br/>
(without searching for it outside the project repo).

# Scenarios

There are three scenarios for `@/exe/bootstrap_env.bash` (but it can be re-run at any time):
1. [`bootstrap_procedure.1.project_creation.md`][bootstrap_procedure.1.project_creation.md]
2. [`bootstrap_procedure.2.initial_installation.md`][bootstrap_procedure.2.initial_installation.md]
3. [`bootstrap_procedure.3.argrelay_upgrade.md`][bootstrap_procedure.3.argrelay_upgrade.md]

# Package management

DEP = `@/conf/env_packages.txt`

Essentially, DEP is what normally called [`requirements.txt`][requirements_txt] and [generated via `pip freeze`][DEP_generation].

DEP excludes packages installed locally in [editable mode][editable_mode] because:
*   version info (e.g. Git commit id) for editable mode quickly become obsolete (not worth committing to the DEP)
*   details of installation are outsourced/delegated to `@/exe/install_project.bash` (already version-controlled)

## Requirement

There are requirements bootstrap script implements (package installation steps):

*   S1: Install (non-local) packages as specified by DEP.

    Purpose: be able to reproduce dev env.

*   S2: Install local packages (owned by the target repo) on top of that.

    Purpose: run the latest from the current branch of target repo (e.g. run tests, run CI, ...).

*   S3: Capture state of current `venv` in DEP.

    Purpose: be able to reproduce dev env.

Note how output of S3 becomes intput of S1.

## Implementation

The bootstrap script should take special care to respect DEP, but:

*   Entire installation process (S1 and S2) is delegated to `@/exe/install_project.bash` instead.

    It is expected that `@/exe/install_project.bash` (normally, not necessarily):
    *   S1: [installs DEP via `pip install`][DEP_installation]
    *   S2: [installs any local packages in editable mode][local_installation]

*   What bootstrap script takes care of directly is S3 above only.

    S3 captures result of S1 and S2.

    Note that if S1 and S2 are implemented as expected, the DEP file **stays unchanged**<br/>
    after repeated bootstrap invocation.

## Package upgrade procedure

In order to upgrade (or downgrade) any DEP package:
*   specify new version in DEP or remove its entry (to give freedom to installation scripts to select other version)
*   install either manually via `pip` or automatically via bootstrap to let `@/exe/install_project.bash` do it
*   re-run bootstrap to re-install and re-capture new DEP

[bootstrap_procedure.1.project_creation.md]: ../dev_notes/bootstrap_procedure.1.project_creation.md
[bootstrap_procedure.2.initial_installation.md]: ../dev_notes/bootstrap_procedure.2.initial_installation
[bootstrap_procedure.3.argrelay_upgrade.md]: ../dev_notes/bootstrap_procedure.3.argrelay_upgrade.md

[requirements_txt]: https://www.google.com/search?q=python+requirements.txt
[editable_mode]: https://github.com/pypa/packaging.python.org/blob/6c27b1f0517ba3db46558a7d0b821ce701307b80/source/guides/distributing-packages-using-setuptools.rst#working-in-development-mode
[DEP_generation]: https://github.com/argrelay/argrelay/blob/v0.5.0.final/exe/bootstrap_env.bash#L499
[DEP_installation]: https://github.com/argrelay/argrelay/blob/v0.5.0.final/exe/install_project.bash#L10
[local_installation]: https://github.com/argrelay/argrelay/blob/v0.5.0.final/exe/install_project.bash#L14

