# Build environments in Shamrock

In Shamrock to ease configuration we provide environment scripts to ease setup on known machines.
They essentially provide preconfigured environments with the correct module load, environment variables and so on.

In essence for any machine that is supported on the repo you can do the following (where you replace `argonne.aurora` by the machine you want):

```bash
# Create a build directory with the environment
./env/new-env --machine argonne.aurora --builddir build --
cd build          # move into it
source ./activate # load the correct modules and ENV vars
shamconfigure     # alias to the correct cmake command
shammake          # alias to ninja build (or make if ninja is unavailable)
```

If you want the list of supported machines just run the help `-h` of the `new-env` script and look at the `Environment list :` section:

```
❯ ../env/new-env -h
usage: new-env [-h] --machine MACHINE --builddir BUILDDIR [--type TYPE] [--lib {shared,object}]

Environment utility for Shamrock

options:
  -h, --help            show this help message and exit
  --machine MACHINE     machine assumed for the environment
  --builddir BUILDDIR   build directory to use
  --type TYPE           build type to use
  --lib {shared,object}
                        shamrock libraries mode
  --                   Everything after this will be forwarded to the env.

Environment list :
  adastra.mi250.intel-llvm       Adastra mi250x Intel LLVM ROCM
  archlinux.acpp                 Archlinux generic AdaptiveCpp
  archlinux.intel-llvm           Archlinux generic Intel LLVM
  argonne.aurora                 Argonne Aurora supercomputer using OneAPI
  calmip.turpan.acpp-cuda        Calmip Turpan AdaptiveCpp
  cbp.acpp                       CBP Machines - AdaptiveCpp
  cbp.intel-llvm                 CBP Machines - Intel LLVM
  ci.intel-llvm.cuda             Github CI Intel llvm cuda
  ci.intel-llvm.rocm             Github CI Intel llvm rocm
  conda.acpp                     Conda AdaptiveCpp
< truncated output >
```

## The `new-env` script

```
❯ ../env/new-env -h
usage: new-env [-h] --machine MACHINE --builddir BUILDDIR [--type TYPE] [--lib {shared,object}]

Environment utility for Shamrock

options:
  -h, --help            show this help message and exit
  --machine MACHINE     machine assumed for the environment
  --builddir BUILDDIR   build directory to use
  --type TYPE           build type to use
  --lib {shared,object}
                        shamrock libraries mode
  --                   Everything after this will be forwarded to the env.

Environment list :
< truncated output >
```

You can see that there are other options available. Let's go through them:

- `--machine` as explained above is the way to select an environment
- `--builddir` is the path of the wanted build directory (can be anywhere on the disk)
- `--type` is used to select the build type (`release`, `debug`, `asan`, ...). Note that this can also be changed later by doing `cmake . -DCMAKE_BUILD_TYPE=Release` (Shamrock Cmake config will check that the type is valid and print the list if you don't know which one to use).
- `--lib` is used to select if you want Shamrock to be built in components (shared libraries) or in a monolithic form which requires a lot more recompilation & larger binaries.
- `--` Anything passed after the two dashes are arguments specific for the environment

Now if you want specific help for an environment you can do the following (for example on the AdaptiveCpp Debian env here):

```
❯ ../env/new-env --machine debian-generic.acpp --builddir build -- --help
------------------------------------------
Running env setup for : Debian generic AdaptiveCpp
Using machine folder :  <Some path>/Shamrock/env/machine/debian-generic/acpp
------------------------------------------
usage: machine/debian-generic/acpp [-h] [--backend BACKEND] [--arch ARCH] [--gen GEN]

Debian generic AdaptiveCpp env for Shamrock

options:
  -h, --help         show this help message and exit
  --backend BACKEND  sycl backend to use
  --arch ARCH        arch to build
  --gen GEN          generator to use (ninja or make)
```

## Environment reset functionality

A new function `reset_env` is now provided in the environment activation scripts generated by `env/new-env`. This function allows you to reset your environment setup in the current build directory. It is useful if you want to clean and regenerate the environment configuration without manually deleting files or rerunning the setup commands by hand.

### What does `reset_env` do?

- Removes the `.env` directory in your build folder (where environment state is stored)
- Re-runs the `env/new-env` command with the original arguments used to set up the environment
- Prints a message reminding you to re-source the `activate` script

### How to use it

After activating your environment (i.e., after running `source ./activate` in your build directory), you can simply run:

```sh
reset_env
```

This will reset the environment setup for your current build directory. After it completes, you should re-run:

```sh
source ./activate
```

to re-activate the environment with the fresh configuration.

**Note:** The `reset_env` function is available in all environments generated with the updated `env/new-env` script. If you do not see this function, try regenerating your environment with the latest version of Shamrock.