Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/phrb/deploy-org

Scripts to hit the ground running with Emacs, org-mode, and ESS for Reproducible Science on your Linux distribution
https://github.com/phrb/deploy-org

docker emacs emacs-configuration emacs-ess emacs-lisp emacs-speaks-statistics org-mode org-mode-configuration

Last synced: 18 days ago
JSON representation

Scripts to hit the ground running with Emacs, org-mode, and ESS for Reproducible Science on your Linux distribution

Awesome Lists containing this project

README 

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