configuring.qmd

---
title: "Appendix: Configuring your Shell"
---

## `.bashrc`: Where do I put my configuration? {#sec-bashrc}

There is a file in your home directory called `.bashrc`. This is where you can customize the way the Bash shell behaves.

There are 2 things you should know how to set:

- Aliases
- Environment Variables, especially `$PATH`

## Aliases

Aliases are shortcuts for commands. You can specify them using `alias` as a line in your `.bashrc` file:

```
alias ll='ls -la'
```

We are defining an alias called `ll` that runs `ls -la` (long listing for directory for all files) here. Once

Some people even add aliases for things they mistype frequently.

## Environment Variables {#sec-environment}

Environment variables are variables which can be seen globally in the Linux (or Windows) system across executables. 

You can get a list of all set environment variables by using the `env` command. Here's an example from my own home system:

```bash
env
```

```
SHELL=/bin/bash
NVM_INC=/home/tladera2/.nvm/versions/node/v21.7.1/include/node
NAME=2QM6TV3
PWD=/home/tladera2
LOGNAME=tladera2
[....]
```

One common environment variable you may have seen is `$JAVA_HOME`, which is used to find the Java Software Development Kit (SDK). (I usually encounter it when a software application yells at me when I haven't set it.)

You can see whether an environment variable is set using `echo`, such as 

```bash
echo $PATH
```

```
/home/tladera2/.local/bin:/home/tladera2/gems/bin:/home/tladera2/.nvm/versions/node/v21.7.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/ [....]
```

### Setting Environment Variables

In Bash, we use the `export` command to declare an environment variable. For example, if we wanted to declare the environment variable `$SAMTOOLS_PATH` we'd do the following:

```bash
# works: note no spaces
export SAMTOOLS_PATH="/home/tladera2/miniconda/bin/"
```

One thing to note is that spacing matters when you declare environment variables. For example, this won't declare the `$SAMTOOLS_PATH` variable:

```bash
# won't work because of spaces
export SAMTOOLS_PATH = "/home/tladera2/miniconda/bin/"
```

Another thing to note is that we declare environment variables differently than we use them. If we wanted to use `SAMTOOLS_PATH` in a script, we use a dollar sign (`$`) in front of it:

```bash
${SAMTOOLS_PATH}/samtools view -c $input_file
```
In this case, the value of `$SAMTOOLS_PATH` will be expanded (substituted) to give the overall path:

```bash
/home/tladera2/miniconda/bin/samtools view -c $input_file
```

### A Very Special Environment Variable: `$PATH` {#sec-path}

The most important environment variable is the `$PATH` variable. This variable is important because it determines where to search for software executables (also called binaries). If you have softwware installed by a package manager (such as `miniconda`), you may need to add the location of your executables to your `$PATH`.

We can add more directories to the `$PATH` by appending to it. You might have seen the following bit of code in your `.bashrc`:

```bash
export PATH=$PATH:/home/tladera2/samtools/
```

In this line, we are adding the path `/home/tladera2/samtools/` to our `$PATH` environment variable. Note that how we refer to the `PATH` variable is different depending on which side the variable is on of the equals sign. 

:::{.callout-note}
## Order matters in your `$PATH`

The order of directories is the order in which `bash` will look for executables. If you install software yourself on `gizmo` (using `make` or such), you should *prepend* the binary directory with your software to the `$PATH`:

```bash
export PATH=/home/tladeras/samtools/:$PATH
```
:::

TLDR: We declare the variable using `export PATH` (no dollar sign) and we append or prepend to this variable using `$PATH` (with dollar sign). This is something that trips me up all the time. 

:::{.callout-note}
## For FH Users

In general, when you use environment modules on `gizmo`, you do not need to modify your `$PATH` variable. You mostly need to modify it when you are compiling executables so that the system can find them. Be sure to use `which` to see where the environment module is actually located:

`which samtools`
:::

### Making your own environment variables

One of the difficulties with working on a cluster is that your scripts may be in one filesystem (`/home/`), and your data might be in another filesystem (`/fh/fast/`). And it might be recommended that you transfer over files to a faster-access filesystem (`/fh/temp/`) to process them.

You can set your own environment variables for use in your own scripts. For example, we might define a `$TCR_FILE_HOME` variable:

```
export TCR_FILE_HOME=/fh/fast/my_tcr_project/
```
to save us some typing across our scripts. We can use this new environment variable like any other existing environment variable:

```bash
#!/bin/Bash
export my_file_location=$TCR_FILE_HOME/fasta_files/
```

:::{.callout-note}
## `.bashrc` versus `.bash_profile` {#sec-bashrc-profile}

Ok, what's the difference between `.bashrc` and `.bash_profile`?

The main difference is when these two files are sourced. `bash_profile` is used when you do an interactive login, and `.bashrc` is used for non-interactive shells.

`.bashrc` should contain the environment variables that you use all the time, such as `$PATH` and `$JAVA_HOME` for example. 

You can get the best of both worlds by including the following line in your `.bash_profile`:

```bash
source ~/.bashrc
```

That way, everything in the `.bashrc` file is loaded when you log in interactively.
:::