.. _configuring bash:

##################
Bash Configuration
##################


Setting the environment (bash)
==============================

For this example, '$HOME/.bashrc' will be used as the target **RC** file.

Other choices include

.. _other rc files:

- '$HOME/.login'
- '$HOME/.bash_profile'
- '$HOME/.profile'



Define constants (bash)
-----------------------

Assuming this help guide has not been followed before..

.. code-block:: shell

   ~ $ RC=$HOME/.bashrc
   ~ $ printf '\n# Developer environment\n' >> $RC
   ~ $ printf '#\n# Local paths\n#\n' >> $RC
   ~ $ printf "export PREFIX=\$HOME/.local\n" >> $RC
   ~ $ printf "export BIN=\$PREFIX/bin\n" >> $RC
   ~ $ printf "export CONFIG_DIRS=\$PREFIX/etc\n" >> $RC
   ~ $ printf "export VAR_DIR=\$PREFIX/var\n" >> $RC
   ~ $ printf "export LOG_DIR=\$VAR_DIR/log\n" >> $RC
   ~ $ printf "export PID_DIR=\$VAR_DIR/pid\n" >> $RC
   ~ $ printf "export USERCONFIG_DIRS=\$HOME/.config\n" >> $RC
   ~ $ printf "export PATH=\$PREFIX/bin:\$PATH\n" >> $RC
   ~ $ printf "export PROJECTS=\$HOME/projects\n" >> $RC
   ~ $ printf "export GITROOT_DIR=\$HOME/git\n" >> $RC

.. note::
   The initial 'printf' statement, is a comment and includes 
   both a leading and trailing "**\\n**"

   This serves two purposes:

      #. The last entry isn't clobbered (when the file is not posix compliant).
      #. Enables continuation with a compliant `posix line`_ file.

   The second 'printf' statement is another comment, serving as a
   reminder to what is being set.
      

   Each line there-after is solely terminated with the *lineending* character
   **\\n**.


The following *environment variables* (**env_vars** or **ENV**) are now
available in *new* shell sessions: [persistent-vars]_

#. PREFIX, location prefix
#. BIN, location of executables
#. CONFIG_DIRS, location of configuration files
#. VAR_DIR, location of variable directories/files e.g. log directories
#. LOG_DIR, location of log directories
#. PID_DIR, location of pid files
#. USERCONFIG_DIRS, location of user configuration files
#. PATH, prepends the local bin directory to the existing *PATH* variable
#. PROJECTS, location of projects
#. GITROOT_DIR, location of git repositories

The purpose of the *CONFIG_DIRS* directory is to serve as a primary source of configuration
template files that can be manipulated pragmatically.

**Congratulations, a shell baseline environment is now defined!**

Alternative RC/shells
---------------------

If one of the `other rc files`_ is used, ensure it's *source*'ed in the shell RC

.. code-block:: shell

   ~ $ cat $HOME/.bashrc
   ...
   source /path/to/rc
   ...

.. seealso::

   For other types of shell, the wikipedia article has a nice summary:

    `Unix Shell <https://en.wikipedia.org/wiki/Unix_shell>`_

.. todo:: environment for shells-not-bash

   [ ] fish

   [ ] zsh

.. [persistent-vars] Upon new login, these variables will be available within
   the session, including **X**/**Wayland**.

.. _posix line: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206