Pokemacs literate config file

Table of Contents

• Documentation
• System
  • Emacs
    • Building
      • From sources
      • With guix
  • Languages
    • Combobulate
    • LSP
    • Flyspell
    • OCaml
    • Rust
    • Python
  • Once emacs is installed:
  • Fonts
  • Configure packages
  • Git hosts and forges
    • Ghub
    • Code Review
  • External files
• Emacs config
• Big Thanks
• Todos

Documentation

Read the manual, you won’t regret it.

System

Emacs

• Your version of emacs should be at least 27.1

Building

From sources

• For this you need to either:
  • git submodule init && git submodule update will download my own version of emacs that should be optimised for lsp
  • clone the emacs repository and either checkout the emacs.27.1 (or higher) branch or compile from the main branch.
• I tend to forget what dependencies are needed by emacs so here is the command I usually invoke before configuring and compiling emacs:

  sudo apt install -y autoconf make gcc texinfo libgtk-3-dev libxpm-dev \
    libjpeg-dev libgif-dev libtiff5-dev libgnutls28-dev libncurses5-dev \
    libjansson-dev libharfbuzz-dev libharfbuzz-bin imagemagick libmagickwand-dev \
    libgccjit-13-dev libgccjit0 gcc-13 libjansson4 libjansson-dev libtree-sitter-dev \
    xaw3dg-dev texinfo libx11-dev libenchant-2-dev pkgconf
      

  export CC="gcc-13"
      

• If you feel confident and better than me at installing emacs from scratch, don’t hesitate to tell me where I’m wrong, I always love to learn
• Once

  ./autogen.sh
      

  and

  ./configure --with-native-compilation -with-json --with-modules --with-harfbuzz --without-compress-install --with-threads --with-included-regex --with-x-toolkit=gtk3 --with-zlib --with-jpeg --with-png --with-imagemagick --with-tiff --with-xpm --with-gnutls --with-xft --with-xml2 --with-mailutils --with-tree-sitter
      

  tell you you can make,

  make -j $(nproc)
      

  then

  sudo make install
      

With guix

• I just follow this link

Languages

Combobulate

You need to initialize the combobulate submodule until it is available on Melpa.

git submodule init && git submodule update

LSP

• In your shell config file:

  export LSP_USE_PLISTS=true
      

Flyspell

• aspell will be installed the first time you start emacs but you’ll still need to install the dictionaries you want to use. In my case this will be:

  sudo apt install aspell-fr aspell-en
      

OCaml

• The best™ way to have an OCaml environment is to install it through opam -

  bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
      

  • Make sure you answer y when asked, this will ensure that opam automatically switches env when you move to a directory with a different opam switch

    opam init
            

• You need to have ocamlformat and ocaml-lsp-server installed in your switch DEPRECATED: pokemacs is now able to install it for you if they’re missing in the current switch

  opam install ocamlformat ocaml-lsp-server -y
      

Rust

• Rust Analyzer
  • install rustup

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
            

  • Update

    rustup update
            

  • Install components

    rustup component add rust-analysis rust-src
            

Python

• Install dependencies

  sudo apt-get install make build-essential libssl-dev zlib1g-dev \
      libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
      libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
      

• Install pyenv

  curl https://pyenv.run | $SHELL
      

• Setup shell env for pyenv: https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv
• Install python

  pyenv install 3.10.5
      

• Install nvm

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | $SHELL
      

• Upgrade pip

  python -m pip install --upgrade pip
      

• Install pyright and other needed packages

  pip install pyright black isort yapf
      

Once emacs is installed:

Just start emacs and let it install all the packages and dependencies.

Fonts

sudo apt install fonts-firacode fonts-material-design-icons-iconfont texlive-fonts-extra

Configure packages

After everything is installed you need to run these two commands just once.

• M-x all-the-icons-install-fonts
• M-x nerd-icons-install-fonts
• M-x pdf-tools-install

Git hosts and forges

Ghub

Ghub is used and needs a bit of tuning first.

In custom.el you can see the line '(auth-sources '("-/.authinfo")), this is where packages looking for authentication sources will look. You can obviously customize it.

Ghub expects to see lines of the following format:

# for GitHub
machine api.github.com login <username>^<package> password <token_from_github>
# for Gitlab
machine gitlab.com/api/v4 login <username>^<package> password <token_from_gitlab>

For pokemacs you need one line only (working towards gitlab integration):

• machine api.github.com login <username>^ghub password <token_from_github>)

Ghub also expects you to have set your username for the hosts you use with:

git config --<global | local> <host>.user <username>

For pokemacs you need to set it for GitHub.

Code Review

Code review needs authentication tokens for forge and code-review. Both tokens need the repo scope active for github and the api scope for gitlab. You need to store them like this in your authinfo file:

machine api.github.com login <username>^forge password <token_from_github>
machine api.github.com login <username>^code-review password <token_from_github>
machine gitlab.com/api login <username>^forge password <token_from_gitlab>
machine gitlab.com/api login <username>^code-review password <token_from_gitlab>

And, of course, you need to let both tools know who you are:

git config --<global | local> github.user <username>
git config --<global | local> gitlab.gitlab.com/api.user <username>

External files

• I have a ​~/org directory that contains 4 files:

org
├── agenda.org
├── calendar​_company.org
├── calendar​_user.org
└── orgzly.org

• This repository is synchronised on all my devices with Syncthing but the directory is checked entirely by org so you can put the files you want in it
• I don’t like having things everywhere. That’s why I configured org-gcal to synchronise with my company’s Google Calendar. For this I needed a secret key that I can’t realistically put in a public repository. This key is located in ~~/.secrets/gcal-secrets.json~

{
    "org-gcal-client-id": "my_id.apps.googleusercontent.com",
    "org-gcal-client-secret": "my_secret_key",
    "calendar-company": "my_company_calendar_id",
    "calendar-user": "my_user_calendar_id"
}

• Thanks to -jz-for this thread

Restart emacs and everything should work

Emacs config

The emacs config is written as literate programming in init.org and this file generates the init.el file (that should never be touched). If you want to try things you can edit init.org and when you’ve finished just hit C-c C-v t (org-babel-tangle).

Big Thanks

• daviwil for his emacs from scratch serie
• hlissner for doomemacs
• Many other that I stupidly didn’t store for small config tricks, bug fixes etc that I found on StackOverflow, Reddit, GitHub, personal blogs etc
• Thanks to @coquera for forcing me to create a README, this was one big example of procrastination
• Thanks to @thriim for the thorough testing
• Thanks to @remyzorg for being unable to choose

Todos

• [X] Rewrite this README in org
• [X] Maybe try this “literate” programming thing
• [ ] I experimented with `emacs-daemon` and `emacsclient` but not enough to make it viable
• [ ] Complete this TODO list
• [ ] Add all the remaining thanks