Open Source Ecosystems

#+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:

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]]!