dotfiles/modules/projects.org

#+TITLE: Projects
#+AUTHOR: Christopher James Hayward
#+EMAIL: chris@chrishayward.xyz

#+PROPERTY: header-args:emacs-lisp :tangle projects.el :comments org
#+PROPERTY: header-args:shell          :tangle no
#+PROPERTY: header-args                  :results silent :eval no-export :comments org

#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[../docs/images/2021-02-13-example-ccls.gif]]

An *IDE*[fn:1] like experience or better can be achieved within Emacs using two *Microsoft*[fn:2] open-source initiatives:

+ *Debug Adapter Protocol*[fn:3]
+ *Language Server Protocol*[fn:4]

* LSP

Support for the *Language Server Protocol*[fn:4] is added to Emacs through the *Lsp mode*[fn:5] package.

#+begin_src emacs-lisp
(use-package lsp-mode
  :commands (lsp lsp-deferred)
  :custom (lsp-idle-delay (* 5 dotfiles/idle)))
#+end_src

** UI improvements

*Lsp ui*[fn:6] provides user interface improvements for *Lsp mode*[fn:5].

#+begin_src emacs-lisp
(use-package lsp-ui
  :after lsp
  :custom (lsp-ui-doc-position 'at-point)
          (lsp-ui-doc-delay 0.500))
#+end_src

** Code completion

Text completion via *Company*[fn:10] =AKA= *Complete Anything*.

#+begin_src emacs-lisp
(use-package company
  :after lsp)
#+end_src

Integrate with *Lsp mode*[fn:5] to provide completion candidates through the *Language Server Protocol*[fn:4].

#+begin_src emacs-lisp
(use-package company-lsp
  :after (lsp company)
  :custom (company-backend 'company-lsp))
#+end_src

* DAP

*Dap mode*[fn:7] provides support for the *Debug Adapter Protocol*[fn:3] inside of Emacs.

#+begin_src emacs-lisp
(use-package dap-mode
  :commands (dap-debug))
#+end_src

* Docker

Manage *Docker*[fn:8] containers with *Docker.el*[fn:9].

#+begin_src emacs-lisp
(use-package docker
  :commands (docker))
#+end_src

Open the container management screen with =SPC k=.

#+begin_src emacs-lisp
(dotfiles/leader
  "k" '(docker :which-key "Docker"))
#+end_src

* Management

Configure *Projectile*[fn:11], a project interaction library for Emacs. It provides a nice set of features for operating on a project level without introducing external dependencies.

#+begin_src emacs-lisp
(use-package projectile
  :custom (projectile-project-search-path '("~/.local/source"))
  :config (projectile-mode))
#+end_src

* Languages

Support for individual programming languages are implemented here. They can be either:

+ LSP / DAP compliant
+ Emacs-mode compliant
+ Third-party module

** Go

Golang is supported using the *Debug Adapter Protocol*[fn:3] and *Language Server Protocol*[fn:4].

*** Setup

Get started by installing *gopls*[fn:14].

#+begin_src shell
GO111MODULE=on go get golang.org/x/tools/gopls@latest
#+end_src

**** Overriding the =$GOPATH=

Set the =$GOPATH= environment variable prior to loading, this is to allow modification of the default value from ~$HOME/go~ to ~$HOME/.go~.

#+begin_src emacs-lisp
(setenv "GOPATH" (concat (getenv "HOME") "/.go/"))
#+end_src

**** Adding =$GOBIN= to the =$PATH=

Additionally, include the ~bin~ subdirectory of the =$GOPATH= in the =$PATH= variable, adding compiled golang programs to the systems path.

#+begin_src emacs-lisp
(setenv "PATH" (concat (getenv "GOPATH") "bin:" (getenv "PATH")))
#+end_src

*** Configuration

Finally we can include the *Go-mode*[fn:15] package, adding integration with *Lsp-mode*[fn:5].

#+begin_src emacs-lisp
(use-package go-mode
  :hook (go-mode . lsp)
  :custom (lsp-go-gopls-server-path "~/.go/bin/gopls"))
#+end_src

Apply some custom behaviour before saving buffers:

+ Format buffer
+ Organize imports

#+begin_src emacs-lisp
(defun dotfiles/go-hook ()
  (add-hook 'before-save-hook #'lsp-format-buffer t t)
  (add-hook 'before-save-hook #'lsp-organize-imports t t))
#+end_src
  
#+begin_src emacs-lisp
(add-hook 'go-mode-hook #'dotfiles/go-hook)
#+end_src

Add a golang source code block structure template with ~<go~:

#+begin_src emacs-lisp
(add-to-list 'org-structure-template-alist '("go" . "src go"))
#+end_src

** HTTP

Interact with HTTP/HTTPS endpoints using the *Ob-http*[fn:16] package. See how it works in my post *Kanye as a Service*[fn:17].

#+begin_src emacs-lisp
(use-package ob-http
  :after org
  :config (org-babel-do-load-languages
            'org-babel-load-languages
            '((http . t))))
#+end_src

** C/C++

Add support for the C/C++ family of languages.

+ Configure the *CCLS*[fn:18] language server
+ Load babel language modules for C/C++
+ Create new structure templates for C/C++
  * ~<cc~ for C
  * ~<cpp~ for C++

#+begin_src emacs-lisp
(use-package ccls
  :hook ((c-mode c++-mode objc-mode cuda-mode) .
         (lambda ()
           (require 'ccls)
           (lsp-deferred)))
  :config (add-to-list 'org-structure-template-alist '("cc" . "src C"))
          (add-to-list 'org-structure-template-alist '("cpp" . "src C++"))
          (org-babel-do-load-languages 'org-babel-load-languages '((C . t))))
#+end_src

** Python

Add support for Python / Python 3 with full support for *DAP*[fn:3] and *LSP*[fn:4].

*** Setup

Install the *pyls*[fn:19] language server.

#+begin_src shell
pip3 install --user "python-language-server[all]"
#+end_src

*Python mode*[fn:20] is an Emacs built in mode for working with Python buffers.

+ Load the babel language modules for Python
+ Add a structure template with ~<py~

#+begin_src emacs-lisp
(use-package python-mode
  :hook (python-mode . lsp-deferred)
  :config (require 'dap-python)
          (add-to-list 'org-src-lang-modes '("python" . python))
          (add-to-list 'org-structure-template-alist '("py" . "src python"))
          (org-babel-do-load-languages 'org-babel-load-languages '((python . t)))
  :custom (python-shell-interpreter "python3") ;; Required if "python" is not python 3.
          (dap-python-executable "python3")    ;; Same as above.
          (dap-python-debugger 'debugpy))
#+end_src

** PlantUML

Download and install *PlantUML*[fn:21], a text-based markup language for creating UML diagrams.

+ Load the babel language module for *PlantUML*
+ Create a structure template with ~<pl~

#+begin_src emacs-lisp
(use-package plantuml-mode
  :after org
  :custom (plantuml-default-exec-mode 'jar)
          (plantuml-jar-path "~/.local/bin/plantuml.jar")
          (org-plantuml-jar-path (expand-file-name "~/.local/bin/plantuml.jar"))
          (org-startup-with-inline-images t)
  :config (add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
          (add-to-list 'org-structure-template-alist '("pl" . "src plantuml"))
          (org-babel-do-load-languages 'org-babel-load-languages '((plantuml . t))))
#+end_src

*** View inside of buffers

Toggle inline images with =SPC t i=.

#+begin_src emacs-lisp
(dotfiles/leader
  "ti" '(org-toggle-inline-images :which-key "Images"))
#+end_src

* Resources

[fn:1] https://en.wikipedia.org/wiki/Integrated_development_environment
[fn:2] https://en.wikipedia.org/wiki/Microsoft_and_open_source
[fn:3] https://microsoft.github.io/debug-adapter-protocol
[fn:4] https://microsoft.github.io/language-server-protocol
[fn:5] https://emacs-lsp.github.io/lsp-mode/
[fn:6] https://emacs-lsp.github.io/lsp-ui/
[fn:7] https://emacs-lsp.github.io/dap-mode/
[fn:8] https://docker.com
[fn:9] https://github.com/Silex/docker.el
[fn:10] https://company-mode.github.io/
[fn:11] https://projectile.mx
[fn:12] https://passwordstore.org
[fn:13] https://git.zx2c4.com/password-store/tree/contrib/emacs
[fn:14] https://pkg.go.dev/golang.org/x/tools/gopls
[fn:15] https://emacswiki.org/emacs/GoMode
[fn:16] https://github.com/zweifisch/ob-http
[fn:17] https://chrishayward.xyz/posts/kanye-as-a-service/
[fn:18] https://github.com/MaskRay/ccls
[fn:19] https://pypi.org/project/python-language-server/
[fn:20] https://emacswiki.org/emacs/PythonProgrammingInEmacs
[fn:21] https://plantuml.com
[fn:22] https://github.com/skuro/plantuml-mode