#+TITLE: Deploy Emacs, Org, and ESS
#+AUTHOR: Pedro Bruel
#+STARTUP: overview indent

[[http://creativecommons.org/licenses/by/4.0/][https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg]]

[[https://github.com/phrb/deploy-org/actions/workflows/ubuntu_20042_lts.yml][https://github.com/phrb/deploy-org/actions/workflows/ubuntu_20042_lts.yml/badge.svg]]
[[https://github.com/phrb/deploy-org/actions/workflows/ubuntu_2104.yml][https://github.com/phrb/deploy-org/actions/workflows/ubuntu_2104.yml/badge.svg]]
[[https://github.com/phrb/deploy-org/actions/workflows/debian_109.yml][https://github.com/phrb/deploy-org/actions/workflows/debian_109.yml/badge.svg]]
[[https://github.com/phrb/deploy-org/actions/workflows/debian_11.yml][https://github.com/phrb/deploy-org/actions/workflows/debian_11.yml/badge.svg]]

Use the Emacs  configuration files in this repository to  deploy Emacs, org, and
ESS in your system. Tested in different Linux distributions using Docker.

- [[#quickstart][Quickstart]]
- [[#install-script-and-docker][Install Script and Docker]]
- [[#contributing][Contributing]]
- [[#linux-distributions-we-wish-to-support][Linux Distributions we Wish to Support]]

* Quickstart
To  install this  configuration in  your system  directly, *backup  your init.el
file*, then run:

#+begin_SRC bash :results output :session *Shell* :eval no-export :exports code
git clone https://github.com/phrb/deploy-org.git
cd deploy-org
sudo ./install/install.sh -i
./install/install.sh -e -t
#+end_SRC

You should  check the Emacs  and org  versions, and you  should see a  =PDF file
produced.=  message, indicating  that  org succesfully  compiled  the test  file
=org/journal/journal.org=   to   =pdf=.    Tests    are   implemented   in   the
=install/install.sh= script.

The =install/install.sh= script will attempt to identify your system and run the
correct  shell   script  for  it.    If  it   fails  for  your   system,  please
[[https://github.com/phrb/deploy-org/issues/new?assignees=&labels=enhancement&template=doesn-t-work-on--my-system-.md&title=Doesn%27t+work+on+%5Bmy+system%5D][submit
an issue]].

* Install Script and Docker
The script's options are:

#+begin_SRC bash :results output :session *Shell* :eval no-export :exports both
./install/install.sh -h
#+end_SRC

#+RESULTS:
: Usage: ./install/install.sh [OPTION]
: 	-i, --install	Install dependencies (requires sudo privileges)
: 	-e, --emacs	Copy "init.el" to user home [/home/phrb/.emacs.d/]
: 	-t, --test	Test user configuration [/home/phrb/.emacs.d/init.el]
: 	-h, --help	Print this message

You can check the status on your  machine of each supported system using Docker.
To check the status for Ubuntu 20.04.2 LTS, for example, run:

#+begin_SRC bash :results output :session *Shell* :eval no-export :exports code
cd docker/ubuntu_20042_lts
sudo docker build .
#+end_SRC

* Contributing
To  contribute, please  fork  the  repository, create  a  new  branch with  your
changes, and submit a pull request to the =main= branch.

** Adding Support for a New Distribution
First, check  the values of the  =NAME=, =VERSION=, and =PRETTY_NAME=  listed on
the =/etc/os-release= file of the distribution you want to add support to:

#+begin_SRC bash :results output :session *Shell* :eval no-export :exports code
OS_NAME=$(cat /etc/os-release | grep "^NAME=" | cut -d= -f2 | cut -d'"' -f2)
OS_VERSION=$(cat /etc/os-release | grep "^VERSION=" | cut -d= -f2 | cut -d'"' -f2)
OS_PRETTY=$(cat /etc/os-release | grep "^PRETTY_NAME=" | cut -d= -f2 | cut -d'"' -f2)

echo "[$OS_NAME] [$OS_VERSION] [$OS_PRETTY]"
#+end_SRC

Add these variables to the =case= structure in the
[[https://github.com/phrb/deploy-org/blob/main/install/setup_os.sh#L46][check_os_eval]]
function in the
[[https://github.com/phrb/deploy-org/blob/main/install/setup_os.sh][setup_os.sh]]
script. Use the =PRETTY_NAME=, or any other variable in =/etc/os-release=, only
if =VERSION= is empty. This way, the script can launch the proper function in a
user's system.

Write a function with the configuration  for the target distribution.  If it's a
Debian-  or   Ubuntu-based  system,   chances  are   the  Ubuntu   functions  in
[[https://github.com/phrb/deploy-org/blob/main/install/setup_os.sh][setup_os.sh]]
will just work.   For example, these are the functions  for Ubuntu 21.04, Debian
10.9, and Debian 11:

#+begin_SRC bash :results output :session *Shell* :eval no-export :exports code
function ubuntu_2104() {
    ubuntu_20042_lts
}

function debian_109() {
    ubuntu_20042_lts
}

function debian_11() {
    ubuntu_20042_lts
}
#+end_SRC

Add your function call to the =case= structure.

Now, write a =Dockerfile= for your distribution and a corresponding GitHub
action.  Use the examples in the
[[https://github.com/phrb/deploy-org/tree/main/docker][docker]] and
[[https://github.com/phrb/deploy-org/tree/main/.github/workflows][workflows]]
directories as starting points.

Make sure that the tests for your distribution pass, and that your changes don't
break support for any other distribution.

Finally, submit a pull request with the
[[https://github.com/phrb/deploy-org/blob/main/.github/PULL_REQUEST_TEMPLATE/support_new_distribution.md][Support
New Distribution]] template.

** Updating =init.org=
Make your changes to =init.org=, tangle  blocks to =init.el= with =C-c C-v C-t=,
and make sure that your changes don't break support for all distributions.

Finally, submit a pull request with the
[[https://github.com/phrb/deploy-org/blob/main/.github/PULL_REQUEST_TEMPLATE/update_init_org.md][Update
init.org]] template.

* Linux Distributions we Wish to Support
Didn't see yours, or one you want?
[[https://github.com/phrb/deploy-org/issues/new?assignees=&labels=enhancement&template=doesn-t-work-on--my-system-.md&title=Doesn%27t+work+on+%5Bmy+system%5D][Submit
an issue]]!

- [ ] Mint
- [ ] Fedora
- [ ] NixOS
- [ ] Guix
- [ ] Kubuntu
- [ ] Older Ubuntu versions
- [ ] Manjaro
- [ ] Arch