mirror of
https://github.com/doomemacs/doomemacs.git
synced 2026-03-26 08:10:39 -07:00
6f40ad55f5
There's little reason for users to use these macros in their private configs over plain ol' `with-eval-after-load` and `use-package`, unless they're writing their own modules. It's my fault for signal boosting them in documentation and whenever I'm asked for help, because beginners now believe they are somehow required for Doom to work correctly (there are guides out there telling beginners that migrating to Doom involves replacing all instances of `with-eval-after-load` and `use-package` in their pre-existing configs with `after!` and `use-package!` -- which was never true). What's more, I plan to replace `use-package`, internally, so the `use-package!` macro won't exist for much longer.
156 lines
5.3 KiB
Org Mode
156 lines
5.3 KiB
Org Mode
#+title: :app irc
|
|
#+subtitle: How neckbeards socialize
|
|
#+created: June 11, 2017
|
|
#+since: 2.0.3
|
|
|
|
* Description :unfold:
|
|
This module turns Emacs into an IRC client, capable of OS notifications.
|
|
|
|
** Maintainers
|
|
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
/This module has no flags./
|
|
|
|
** Packages
|
|
- [[doom-package:circe]]
|
|
- [[doom-package:circe-notifications]]
|
|
|
|
** Hacks
|
|
/No hacks documented for this module./
|
|
|
|
** TODO Changelog
|
|
# This section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
|
|
|
This module requires:
|
|
- [[https://www.gnutls.org/][GnuTLS]], for secure IRC connections to work.
|
|
|
|
This should be available through your OS package manager.
|
|
|
|
** macOS
|
|
#+begin_src sh
|
|
brew install gnutls
|
|
#+end_src
|
|
|
|
** Debian / Ubuntu
|
|
#+begin_src sh
|
|
apt install gnutls-bin
|
|
#+end_src
|
|
|
|
** Arch Linux
|
|
#+begin_src sh
|
|
pacman -S gnutls
|
|
#+end_src
|
|
** NixOS
|
|
#+begin_src nix
|
|
environment.systemPackages = [ pkgs.gnutls ];
|
|
#+end_src
|
|
|
|
* TODO Usage
|
|
#+begin_quote
|
|
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
To connect to IRC use ~M-x =irc~.
|
|
|
|
When in a circe buffer these keybindings will be available:
|
|
| command | key | description |
|
|
|-----------------------------+-----------------+----------------------------------------------|
|
|
| ~+irc/tracking-next-buffer~ | [[kbd:][<localleader> a]] | Switch to the next active buffer |
|
|
| ~circe-command-JOIN~ | [[kbd:][<localleader> j]] | Join a channel |
|
|
| ~+irc/send-message~ | [[kbd:][<localleader> m]] | Send a private message |
|
|
| ~circe-command-NAMES~ | [[kbd:][<localleader> n]] | List the names of the current channel |
|
|
| ~circe-command-PART~ | [[kbd:][<localleader> p]] | Part the current channel |
|
|
| ~+irc/quit~ | [[kbd:][<localleader> Q]] | Kill the current circe session and workgroup |
|
|
| ~circe-reconnect~ | [[kbd:][<localleader> R]] | Reconnect the current server |
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
/This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument
|
|
(a plist) takes the same arguments as ~circe-network-options~:
|
|
#+begin_src emacs-lisp
|
|
;; if you omit =:host=, ~SERVER~ will be used instead.
|
|
(with-eval-after-load 'circe
|
|
(set-irc-server! "irc.libera.chat"
|
|
`(:tls t
|
|
:port 6697
|
|
:nick "doom"
|
|
:sasl-username "myusername"
|
|
:sasl-password "mypassword"
|
|
:channels ("#emacs"))))
|
|
#+end_src
|
|
|
|
However, *it is a obviously a bad idea to store your password in plaintext,* so
|
|
[[https://github.com/emacs-circe/circe/wiki/Configuration#safer-password-management][it's recommend]] that you use ~auth-source~ (built into Emacs) to safely pull
|
|
passwords from a password manager or OS keychain (remember to enable the :os
|
|
macos or :tools pass modules if you want integration into the MacOS keychain or
|
|
[[https://www.passwordstore.org/][Pass]]):
|
|
#+begin_src emacs-lisp
|
|
;;; in $DOOMDIR/config.el
|
|
(with-eval-after-load 'circe
|
|
(defun fetch-password (&rest params)
|
|
(require 'auth-source)
|
|
(if-let* ((match (car (apply #'auth-source-search params)))
|
|
(secret (plist-get match :secret)))
|
|
(if (functionp secret)
|
|
(funcall secret)
|
|
secret)
|
|
(user-error "Password not found for %S" params)))
|
|
|
|
(set-irc-server! "irc.libera.chat"
|
|
'(:tls t
|
|
:port 6697
|
|
:nick "doom"
|
|
:sasl-password
|
|
(lambda (server)
|
|
(fetch-password :user "forcer" :host "irc.libera.chat"))
|
|
:channels ("#emacs"))))
|
|
#+end_src
|
|
|
|
If Doom's [[doom-module::tools pass]] module is enabled, ~auth-source~ can integrate
|
|
with [[https://www.passwordstore.org/][Pass]].
|
|
|
|
#+begin_quote
|
|
A common mistake is to interpolate the return value of your secrets retrieval
|
|
function into the plist you pass to ~set-irc-server!~. This means that not
|
|
only will your secrets will be stored, in plaintext, somewhere in Emacs
|
|
state, but your password manager (or GnuPG) will likely prompt you for your
|
|
GPG key passphrase when the ~set-irc-server!~ call is made! For example,
|
|
don't do this!
|
|
|
|
(set-irc-server! "irc.libera.chat"
|
|
`(:tls t
|
|
:port 6697
|
|
:nick "doom"
|
|
:sasl-username ,(fetch-password "irc/libera.chat")
|
|
:sasl-password ,(fetch-password "irc/libera.chat")
|
|
:channels ("#emacs")))
|
|
|
|
Do this, instead:
|
|
|
|
(set-irc-server! "irc.libera.chat"
|
|
'(:tls t
|
|
:port 6697
|
|
:nick "doom"
|
|
:sasl-username (+pass-get-user "irc/libera.chat")
|
|
:sasl-password (+pass-get-secret "irc/libera.chat")
|
|
:channels ("#emacs")))
|
|
#+end_quote
|
|
|
|
* TODO Troubleshooting
|
|
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
|
|
|
* Frequently asked questions
|
|
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
|
#+end_quote
|